如何调用零一万物API-阿里云帮助中心

通过阅读本文您可以掌握使用API调用零一万物模型服务的方法。您可以使用Python或Java版本的Dashscope SDK，或使用HTTP接口来调用。

零一万物

说明

支持的领域 / 任务：AIGC、语言理解、深度推理、文本生成

Yi系列模型是零一万物推出的高品质大语言模型。其中Yi-Large为LMSYS榜单TOP10唯一的中国模型。全系模型均经过高精度微调，指令遵循强化。对于复杂语言理解、深度推理、文本生成，均有优秀的结果表现。

模型名称	上下文长度	最大输入	输入输出成本	免费额度（注）
模型名称	（Token数）		输入输出成本	免费额度（注）

模型名称	上下文长度	最大输入	输入输出成本	免费额度（注）
	（Token数）
yi-large	32,000	32,000	目前仅供免费体验。免费额度用完后不可调用，敬请关注后续动态。	各100万Token（需申请）有效期：申请通过后180天内
yi-medium
yi-large-rag 有实时联网能力	16,000	16,000
yi-large-turbo

模型概览

模型名	模型简介
Yi-Large	Yi-Large是零一万物的千亿参数大语言模型，是LM SYS榜单TOP10上唯一国产大模型。具备超强的问答、推理及文本生能力。适用于复杂语言理解、深度内容创作设计等复杂场景。上下文16K文本长度可自由设定。
Yi-Medium	Yi-Medium是零一万物推出的中等尺寸模型，并进行了升级强化微调，深度优化指令遵循能力。能力均衡，性价比高。适用于日常聊天、问答、协作、翻译等通用场景，是大规模应用大模型的理想选择。支持32K文本长度。
Yi-Large-RAG	Yi-Large-RAG是零一万物推出的高阶模型服务，带有实时联网搜索能力。模型会判断是否需要最新的网络信息，进而获取最新信息后进行综合推理，输出答案。适用于需要结合实时信息，进行复杂推理、文本生成等场景。支持16K文本长度。
Yi-Large-Turbo	Yi-Large-Turbo是零一万物推出的超高性价比的模型服务。根据推理性能、速度、成本进行综合均衡优化，保证高质量推理的同时，成本低，速度快。适用于通用综合性、复合性高的场景。支持16K文本长度。

SDK使用

前提条件

您需要已获取API Key并配置API Key到环境变量。如果通过SDK调用，还需要安装DashScope SDK。
您需要登录百炼控制台界面，在模型广场找到您需要申请的零一万物大语言模型，单击立即申请，等待申请完成即可进行调用。

示例代码

以下示例展示了调用Yi模型对一个用户指令进行响应的代码。

Python

Java

Python

        
# coding=utf-8
import dashscope

messages = [{'role': 'system', 'content': 'You are a helpful assistant.'},
            {'role': 'user', 'content': '你是谁'}]
response = dashscope.Generation.call(
    model='yi-medium',
    messages=messages,
)
print(response)

Java

        

          
      
        
// 建议dashscope SDK的版本 >= 2.12.0
import java.util.Arrays;
import java.lang.System;
import com.alibaba.dashscope.aigc.generation.Generation;
import com.alibaba.dashscope.aigc.generation.GenerationParam;
import com.alibaba.dashscope.aigc.generation.GenerationResult;
import com.alibaba.dashscope.common.Message;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.JsonUtils;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation();
        Message systemMsg = Message.builder()
                .role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant.")
                .build();
        Message userMsg = Message.builder()
                .role(Role.USER.getValue())
                .content("你是谁？")
                .build();
        GenerationParam param = GenerationParam.builder()
                // 若没有配置环境变量，请用百炼API Key将下行替换为：.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("yi-medium")
                .messages(Arrays.asList(systemMsg, userMsg))
                .build();
        return gen.call(param);
    }
    public static void main(String[] args) {
        try {
            GenerationResult result = callWithMessage();
            System.out.println(JsonUtils.toJson(result));
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            // 使用日志框架记录异常信息
            System.err.println("An error occurred while calling the generation service: " + e.getMessage());
        }
        System.exit(0);
    }
}

参数配置

参数	类型	默认值	说明

参数	类型	默认值	说明
model	string	-	模型名称。
messages	array	-	输入到大模型的消息列表，列表中每个元素为哈希表，包含2个key：role和content，其中role支持user、assistant、system，content为对应role的文本输入。示例： `[{'role': 'system', 'content': 'You are a helpful assistant.'}, {'role': 'user', 'content': '你好'}]`
temperature	float	0.3	取值范围： `[0.0, 2.0)`。控制生成结果的发散性和集中性。数值越小，越集中；数值越大，越发散。
top_p	float	0.9	取值范围： `[0.0, 1.0)`。控制生成结果的随机性。数值越小，随机性越弱；数值越大，随机性越强。
max_tokens	integer	100	指定模型在生成内容时token的最大数量，它定义了生成的上限，但不保证每次都会产生到这个数量。

返回结果

返回结果示例

JSON

        

          
      
        
{
    "output": {
        "choices": [
            {
                "message": {
                    "content": "你好！今天我能帮你什么？",
                    "role": "assistant"
                },
                "index": 0,
                "finish_reason": "stop"
            }
        ]
    },
    "usage": {
        "total_tokens": 15,
        "input_tokens": 8,
        "output_tokens": 7
    },
    "request_id": "23066782-2f2b-9f66-82f0-7c26a186b470"
}

返回参数说明

返回参数	类型	说明

返回参数	类型	说明
status_code	integer	200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。
request_id	string	系统生成的标志本次调用的id。
code	string	表示请求失败，表示错误码，成功忽略。
message	string	失败，表示失败详细信息，成功忽略。
output	object	调用结果信息。
output.choices	array	返回结果列表
output.choices[x].finish_reason	string	回复停止的原因
output.choices[x].message	string	返回结果
output.choices[x].message.role	string	返回结果role
output.choices[x].message.content	string	返回结果内容
usage	object	计量信息，表示本次请求计量数据，当前模型无计量信息，此处为默认值。
usage.input_tokens	integer	用户输入文本转换成token后的长度。
usage.output_tokens	integer	模型生成回复转换为token后的长度。
usage.total_tokens	integer	用户输入+模型生成回复转换为token后的长度。

HTTP调用接口

功能描述

Yi模型同时支持 HTTP 接口调用来完成客户的响应，详情如下：

前提条件

您需要已获取API Key并配置API Key到环境变量。
您需要登录百炼控制台界面，在模型广场找到您需要申请的零一万物大语言模型，单击立即申请，等待申请完成即可进行调用。

提交接口调用

POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation

入参描述

传参方式	字段	类型	必选	描述	示例值

传参方式	字段	类型	必选	描述	示例值
Header	Content-Type	string	是	请求类型：application/json	application/json
	Authorization	string	是	API-Key，例如：Bearer d1**2a	Bearer d1**2a
	X-DashScope-WorkSpace	string	否	指明本次调用需要使用的workspace；需要注意的是，对于子账号Apikey调用，此参数为必选项，子账号必须归属于某个workspace才能调用；对于主账号Apikey此项为可选项，添加则使用对应的workspace身份，不添加则使用主账号身份。	ws_QTggmeAxxxxx
Body	model	string	是	指明需要调用的模型。	yi-large
	input.messages	array	是	包含迄今为止对话的消息列表。	这是一个结构体的列表，每个元素类似如下：`{"role": "user", "content": "你好"}` role 只可以为system,user,assistant 其一，content 不得为空。
	parameters.temperature	float	否	取值范围： `[0.0, 2.0)`。控制生成结果的发散性和集中性。数值越小，越集中；数值越大，越发散。	0.3
	parameters.top_p	float	否	取值范围： `[0.0, 1.0)`。控制生成结果的随机性。数值越小，随机性越弱；数值越大，随机性越强。	0.9
	parameters.max_tokens	integer	否	指定模型在生成内容时token的最大数量，它定义了生成的上限，但不保证每次都会产生到这个数量。	100

出参描述

字段	类型	描述	示例值

字段	类型	描述	示例值
status_code	integer	200（HTTPStatus.OK）表示请求成功，否则表示请求失败，可以通过code获取错误码，通过message字段获取错误详细信息。	200
request_Id	string	系统生成的标志本次调用的id。	23066782-2f2b-9f66-82f0-7c26a186b470
output.choices[x].finish_reason	string	停止原因	stop
output.choices[x].message.role	string	返回结果role	assistant
output.choices[x].message.content	string	返回结果内容	你好！今天我能帮你什么？
usage	object	计量信息，表示本次请求计量数据，当前模型无计量信息，此处为默认值。	"usage": { "total_tokens": 15, "input_tokens": 8, "output_tokens": 7 }
usage.input_tokens	integer	用户输入文本转换成token后的长度。	8
usage.output_tokens	integer	模型生成回复转换为token后的长度。	7
usage.total_tokens	integer	用户输入+模型生成的回复转换为token后的长度。	15

请求示例

以下示例展示通过CURL命令来调用yi-large模型的脚本。

curl

        

          
      
        
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "yi-large",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你好"
            }
        ]
    }
}'

响应示例

JSON

        

          
      
        
{
    "output": {
        "choices": [
            {
                "message": {
                    "content": "你好！今天我能帮你什么？",
                    "role": "assistant"
                },
                "index": 0,
                "finish_reason": "stop"
            }
        ]
    },
    "usage": {
        "total_tokens": 15,
        "input_tokens": 8,
        "output_tokens": 7
    },
    "request_id": "23066782-2f2b-9f66-82f0-7c26a186b470"
}

异常响应示例

在访问请求出错的情况下，输出的结果中会通过 code 和 message 指明出错原因。

JSON

        
{
    "code":"InvalidApiKey",
    "message":"Invalid API-key provided.",
    "request_id":"fb53c4ec-1c12-4fc4-a580-cdb7c3261fc1"
}

状态码说明

大模型服务平台通用状态码请查阅：错误信息