通义千问API参考

本文介绍通义千问API的输入输出参数。

模型介绍、选型建议和使用方法请参考文本生成。也可以查看特定模型的用法:长上下文(Qwen-Long)、视觉理解(通义千问VL)、音频理解(通义千问Audio)、数学模型代码模型

您可以通过OpenAI 兼容或DashScope的方式调用通义千问API。

OpenAI 兼容

公有云

使用SDK调用时需配置的base_url:https://dashscope.aliyuncs.com/compatible-mode/v1

使用HTTP方式调用时需配置的endpoint:POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions

金融云

使用SDK调用时需配置的base_url:https://dashscope-finance.aliyuncs.com/compatible-mode/v1

使用HTTP方式调用时需配置的endpoint:POST https://dashscope-finance.aliyuncs.com/compatible-mode/v1/chat/completions

您需要已获取API Key配置API Key到环境变量。如果通过OpenAI SDK进行调用,还需要安装SDK

请求体

文本输入

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus", # 模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
    messages=[
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': '你是谁?'}],
    )
    
print(completion.model_dump_json())

Node.js

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

async function main() {
    const completion = await openai.chat.completions.create({
        model: "qwen-plus",  //模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "你是谁?" }
        ],
    });
    console.log(JSON.stringify(completion))
}

main();

HTTP

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "你是谁?"
        }
    ]
}'

PHP

<?php
// 设置请求的URL
$url = 'https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions';
// 若没有配置环境变量,请用百炼API Key将下行替换为:$apiKey = "sk-xxx";
$apiKey = getenv('DASHSCOPE_API_KEY');
// 设置请求头
$headers = [
    'Authorization: Bearer '.$apiKey,
    'Content-Type: application/json'
];
// 设置请求体
$data = [
    // 模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
    "model" => "qwen-plus",
    "messages" => [
        [
            "role" => "system",
            "content" => "You are a helpful assistant."
        ],
        [
            "role" => "user",
            "content" => "你是谁?"
        ]
    ]
];
// 初始化cURL会话
$ch = curl_init();
// 设置cURL选项
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
// 执行cURL会话
$response = curl_exec($ch);
// 检查是否有错误发生
if (curl_errno($ch)) {
    echo 'Curl error: ' . curl_error($ch);
}
// 关闭cURL资源
curl_close($ch);
// 输出响应结果
echo $response;
?>

C#

using System.Net.Http.Headers;
using System.Text;

class Program
{
    private static readonly HttpClient httpClient = new HttpClient();

    static async Task Main(string[] args)
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:string? apiKey = "sk-xxx";
        string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");

        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("API Key 未设置。请确保环境变量 'DASHSCOPE_API_KEY' 已设置。");
            return;
        }

        // 设置请求 URL 和内容
        string url = "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions";
        // 模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
        string jsonContent = @"{
            ""model"": ""qwen-plus"",
            ""messages"": [
                {
                    ""role"": ""system"",
                    ""content"": ""You are a helpful assistant.""
                },
                {
                    ""role"": ""user"", 
                    ""content"": ""你是谁?""
                }
            ]
        }";

        // 发送请求并获取响应
        string result = await SendPostRequestAsync(url, jsonContent, apiKey);

        // 输出结果
        Console.WriteLine(result);
    }

    private static async Task<string> SendPostRequestAsync(string url, string jsonContent, string apiKey)
    {
        using (var content = new StringContent(jsonContent, Encoding.UTF8, "application/json"))
        {
            // 设置请求头
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

            // 发送请求并获取响应
            HttpResponseMessage response = await httpClient.PostAsync(url, content);

            // 处理响应
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }
            else
            {
                return $"请求失败: {response.StatusCode}";
            }
        }
    }
}

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}
type RequestBody struct {
	Model    string    `json:"model"`
	Messages []Message `json:"messages"`
}

func main() {
	// 创建 HTTP 客户端
	client := &http.Client{}
	// 构建请求体
	requestBody := RequestBody{
		// 模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
		Model: "qwen-plus",
		Messages: []Message{
			{
				Role:    "system",
				Content: "You are a helpful assistant.",
			},
			{
				Role:    "user",
				Content: "你是谁?",
			},
		},
	}
	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		log.Fatal(err)
	}
	// 创建 POST 请求
	req, err := http.NewRequest("POST", "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions", bytes.NewBuffer(jsonData))
	if err != nil {
		log.Fatal(err)
	}
	// 设置请求头
	// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey := "sk-xxx"
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")
	// 发送请求
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	// 读取响应体
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	// 打印响应内容
	fmt.Printf("%s\n", bodyText)
}

Java

OpenAI未提供Java SDK。如需通过Java SDK调用,请参考本文的DashScope章节。

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

import com.google.gson.Gson;

public class Main {

    static class Message {
        String role;
        String content;

        public Message(String role, String content) {
            this.role = role;
            this.content = content;
        }
    }

    static class RequestBody {
        String model;
        Message[] messages;

        public RequestBody(String model, Message[] messages) {
            this.model = model;
            this.messages = messages;
        }
    }

    public static void main(String[] args) {
        try {
            // 创建请求体
            RequestBody requestBody = new RequestBody(
                    "qwen-plus",
                    new Message[] {
                            new Message("system", "You are a helpful assistant."),
                            new Message("user", "你是谁?")
                    }
            );

            // 将请求体转换为 JSON
            Gson gson = new Gson();
            String jsonInputString = gson.toJson(requestBody);

            // 创建 URL 对象
            URL url = new URL("https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions");
            HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();

            // 设置请求方法为 POST
            httpURLConnection.setRequestMethod("POST");
            httpURLConnection.setRequestProperty("Content-Type", "application/json; utf-8");
            httpURLConnection.setRequestProperty("Accept", "application/json");

            // 若没有配置环境变量,请用百炼API Key将下行替换为:String apiKey = "sk-xxx";
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            String auth = "Bearer " + apiKey;
            httpURLConnection.setRequestProperty("Authorization", auth);

            // 启用输入输出流
            httpURLConnection.setDoOutput(true);

            // 写入请求体
            try (OutputStream os = httpURLConnection.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            // 获取响应码
            int responseCode = httpURLConnection.getResponseCode();
            System.out.println("Response Code: " + responseCode);

            // 读取响应体
            try (BufferedReader br = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream(), StandardCharsets.UTF_8))) {
                StringBuilder response = new StringBuilder();
                String responseLine;
                while ((responseLine = br.readLine()) != null) {
                    response.append(responseLine.trim());
                }
                System.out.println("Response Body: " + response);
            }

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            System.exit(0);
        }
    }
}

流式输出

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[{'role': 'system', 'content': 'You are a helpful assistant.'},
                {'role': 'user', 'content': '你是谁?'}],
    stream=True,
    stream_options={"include_usage": True}
    )
for chunk in completion:
    print(chunk.model_dump_json())

Node.js

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

async function main() {
    const completion = await openai.chat.completions.create({
        model: "qwen-plus",
        messages: [
            {"role": "system", "content": "You are a helpful assistant."},
            {"role": "user", "content": "你是谁?"}
        ],
        stream: true,
    });
    for await (const chunk of completion) {
        console.log(JSON.stringify(chunk));
    }
}

main();

curl

curl --location "https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions" \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header "Content-Type: application/json" \
--data '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "你是谁?"
        }
    ],
    "stream":true
}'

图像输入

关于大模型分析图像的更多用法,请参考:视觉理解

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-vl-plus",
    messages=[{"role": "user","content": [
            {"type": "text","text": "这是什么"},
            {"type": "image_url",
             "image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}
            ]}]
    )
print(completion.model_dump_json())

Node.js

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

async function main() {
    const response = await openai.chat.completions.create({
        model: "qwen-vl-max",
        messages: [{role: "user",content: [
            { type: "text", text: "这是什么?" },
            { type: "image_url",image_url: {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}
        ]}]
    });
    console.log(JSON.stringify(response));
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "model": "qwen-vl-plus",
  "messages": [{
      "role": "user",
      "content": 
      [{"type": "text","text": "这是什么"},
       {"type": "image_url","image_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"}}]
    }]
}'

视频输入

关于大模型分析视频的更多用法,请参考:视觉理解

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-vl-max-latest",
    messages=[{
        "role": "user",
        "content": [
            {
                "type": "video",
                "video": [
                    "https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
                    "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
                    "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
                    "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg"]
            },
            {
                "type": "text",
                "text": "描述这个视频的具体过程"
            }]}]
)
print(completion.model_dump_json())

Node.js

// 确保之前在 package.json 中指定了 "type": "module"
import OpenAI from "openai"; 

const openai = new OpenAI({
    // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
    apiKey: process.env.DASHSCOPE_API_KEY, 
    baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
});

async function main() {
    const response = await openai.chat.completions.create({
        model: "qwen-vl-max-latest",
        messages: [{
            role: "user",
            content: [
                {
                    type: "video",
                    video: [
                        "https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg"
                    ]
                },
                {
                    type: "text",
                    text: "描述这个视频的具体过程"
                }
        ]}]
    });
    console.log(JSON.stringify(response));
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
    "model": "qwen-vl-max-latest",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "video",
                    "video": [
                        "https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
                        "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg"
                    ]
                },
                {
                    "type": "text",
                    "text": "描述这个视频的具体过程"
                }
            ]
        }
    ]
}'

工具调用

完整的Function Call流程代码请参考:Function Call(工具调用)

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope SDKbase_url
)

tools = [
    # 工具1 获取当前时刻的时间
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "当你想知道现在的时间时非常有用。",
            "parameters": {}  # 因为获取当前时间无需输入参数,因此parameters为空字典
        }
    },  
    # 工具2 获取指定城市的天气
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "当你想查询指定城市的天气时非常有用。",
            "parameters": {  
                "type": "object",
                "properties": {
                    # 查询天气时需要提供位置,因此参数设置为location
                    "location": {
                        "type": "string",
                        "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                    }
                },
                "required": ["location"]
            }
        }
    }
]
messages = [{"role": "user", "content": "杭州天气怎么样"}]
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=messages,
    tools=tools
)

print(completion.model_dump_json())

Node.js

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

const messages = [{"role": "user", "content": "杭州天气怎么样"}];
const tools = [
// 工具1 获取当前时刻的时间
{
    "type": "function",
    "function": {
        "name": "get_current_time",
        "description": "当你想知道现在的时间时非常有用。",
        // 因为获取当前时间无需输入参数,因此parameters为空
        "parameters": {}  
    }
},  
// 工具2 获取指定城市的天气
{
    "type": "function",
    "function": {
        "name": "get_current_weather",
        "description": "当你想查询指定城市的天气时非常有用。",
        "parameters": {  
            "type": "object",
            "properties": {
                // 查询天气时需要提供位置,因此参数设置为location
                "location": {
                    "type": "string",
                    "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                }
            },
            "required": ["location"]
        }
    }
}
];

async function main() {
    const response = await openai.chat.completions.create({
        model: "qwen-plus",
        messages: messages,
        tools: tools,
    });
    console.log(JSON.stringify(response));
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "杭州天气怎么样"
        }
    ],
    "tools": [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "当你想知道现在的时间时非常有用。",
            "parameters": {}
        }
    },
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "当你想查询指定城市的天气时非常有用。",
            "parameters": {
                "type": "object",
                "properties": {
                    "location":{
                        "type": "string",
                        "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                    }
                },
                "required": ["location"]
            }
        }
    }
  ]
}'

联网搜索

Python

import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"), 
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # 填写DashScope服务的base_url
)
completion = client.chat.completions.create(
    model="qwen-plus",
    messages=[
        {'role': 'system', 'content': 'You are a helpful assistant.'},
        {'role': 'user', 'content': '中国队在巴黎奥运会获得了多少枚金牌'}],
    extra_body={
        "enable_search": True
    }
    )
print(completion.model_dump_json())

Node.js

import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);
async function main() {
    const completion = await openai.chat.completions.create({
        model: "qwen-plus",  //模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
        messages: [
            { role: "system", content: "You are a helpful assistant." },
            { role: "user", content: "中国队在巴黎奥运会获得了多少枚金牌" }
        ],
        enable_search:true
    });
    console.log(JSON.stringify(completion))
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user", 
            "content": "中国队在巴黎奥运会获得了多少枚金牌"
        }
    ],
    "enable_search": true
}'

异步调用

import os
import asyncio
from openai import AsyncOpenAI
import platform

client = AsyncOpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)

async def main():
    response = await client.chat.completions.create(
        messages=[{"role": "user", "content": "你是谁"}],
        model="qwen-plus",
    )
    print(response.model_dump_json())

if platform.system() == "Windows":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
asyncio.run(main())

文档理解

当前仅qwen-long模型支持对文档进行分析,详细用法请参考:长上下文

Python

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
file_object = client.files.create(file=Path("百炼系列手机产品介绍.docx"), purpose="file-extract")
completion = client.chat.completions.create(
    model="qwen-long",
    messages=[
        {'role': 'system', 'content': f'fileid://{file_object.id}'},
        {'role': 'user', 'content': '这篇文章讲了什么?'}
    ]
)
print(completion.model_dump_json())

Node.js

import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI(
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
        apiKey: process.env.DASHSCOPE_API_KEY,
        baseURL: "https://dashscope.aliyuncs.com/compatible-mode/v1"
    }
);

async function getFileID() {
    const fileObject = await openai.files.create({
        file: fs.createReadStream("百炼系列手机产品介绍.docx"),
        purpose: "file-extract"
    });
    return fileObject.id;
}   

async function main() {
    const fileID = await getFileID();
    const completion = await openai.chat.completions.create({
        model: "qwen-long",  //模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
        messages: [
            { role: "system", content: `fileid://${fileID}`},
            { role: "user", content: "这篇文章讲了什么?" }
        ],
    });
    console.log(JSON.stringify(completion))
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-long",
    "input": {
        "messages": [
            {"role": "system","content": "fileid://file-fe-xxx"},
            {"role": "user","content": "这篇文章讲了什么?"}
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'

文字提取

qwen-vl-ocrOCR专用模型。为保证模型效果,目前模型内部会采用固定的文本作为输入文本,用户自定义的文本不会生效。关于qwen-vl-ocr的更多用法,请参见文字提取(OCR)

Python

# pip install -U openai
import os
from openai import OpenAI

client = OpenAI(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-vl-ocr",
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg",
                    "min_pixels": 28 * 28 * 4,
                    "max_pixels": 1280 * 784
                },
                # 目前为保证识别效果,模型内部会统一使用"Read all the text in the image."作为text的值,用户输入的文本不会生效。
                {"type": "text", "text": "Read all the text in the image."},
            ]
        }
    ],
    top_p=0.01,
    temperature=0.1,
    max_tokens=2000)
        
print(completion.model_dump_json())

Node.js

import OpenAI from 'openai';

const openai = new OpenAI({
  // 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey: "sk-xxx",
  apiKey: process.env.DASHSCOPE_API_KEY,
  baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
});

async function main() {
  const response = await openai.chat.completions.create({
    model: 'qwen-vl-ocr',
    messages: [
      {
        role: 'user',
        content: [
        // 目前为保证模型效果,模型内部会统一使用"Read all the text in the image."作为text的值,用户输入的文本不会生效。
          { type: 'text', text: 'Read all the text in the image.' },
          {
            type: 'image_url',
            image_url: {
              url: 'https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg',
            },
              "min_pixels": 28 * 28 * 4,
              "max_pixels": 1280 * 784
          }
        ],
      },
    ],
    top_p: 0.01,
    temperature: 0.1,
    max_tokens: 2000,
  });
  console.log(response.choices[0].message.content);
}

main();

curl

curl -X POST https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen-vl-ocr",
  "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "image_url",
                    "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg",
                    "min_pixels": 3136,
                    "max_pixels": 1003520
                },
                {"type": "text", "text": "Read all the text in the image."}
            ]
        }
    ],
    "top_p": 0.01,
    "temperature": 0.1,
    "repetition_penalty": 1.05,
    "max_tokens":2000
}'

model string (必选)

模型名称。

支持的模型:通义千问大语言模型(商业版、开源版、Qwen-Long)、通义千问VL、数学模型、代码模型

通义千问Audio暂不支持OpenAI兼容模式,仅支持DashScope方式。

具体模型名称和计费,请参见模型列表

messages array (必选)

由历史对话组成的消息列表。

消息类型

System Message object (可选)

模型的目标或角色。如果设置系统消息,请放在messages列表的第一位。

属性

content string (必选)

消息内容。

role string (必选)

固定为system

User Message object (必选)

用户发送给模型的消息。

属性

content string 或 array (必选)

消息内容。如果您的输入只有文本,则为string类型;如果您的输入包含图像等多模态数据,则为array类型。

如需传入音频给通义千问Audio模型,请前往DashScope查看,暂不支持使用OpenAI兼容的方式。

属性

type string (必选)

有三个可取值:textimage_urlvideo

text string

type参数为text时,是必选参数。

用户的输入文本。

示例值:{"type":"text","text": "这是什么"}。

image_url string

type参数为image_url,且模型为视觉理解类模型时,是必选参数,如模型为qwen-vl-max、qwen-vl-plus等。

用户的输入图像信息。可以为图片的URL或本地路径信息。传入本地文件请参考使用本地文件

示例值:{"type": "image_url", "image_url": "https://img-yy-xx.jpg"}。

video array

type参数为video时,且模型为视觉理解类模型时,是必选参数,如模型为qwen-vl-max、qwen-vl-plus等。

用户的输入视频信息。您可以通过图片列表传入。

示例值:{"type":"video","video": ["https://img-xx1.jpg","https://img-xx2.jpg"]}

如果您需要直接输入视频文件,请提交工单进行申请以及获取使用方式。

min_pixels integer (可选)

仅适用于通义千问OCR模型。

输入图像的最小像素。

默认值:3136(28*28*4)。

最小值:10*10。

在通义千问VLOCR模型中,图像转换为Token的规则:每28x28像素对应一个Token。即min_pixels的默认值为4Token。

使用方法

  • 当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。

  • 当输入图像像素小于min_pixels时,会将图像按原比例放大,直到总像素高于min_pixels

  • 当输入图像像素大于max_pixels时,会将图像按原比例缩小,直到总像素低于max_pixels

max_pixels integer (可选)

仅适用于通义千问OCR模型。

输入图像的最大像素。

默认值:1003520(28*28*1280)。

最大值:28*28*30000。

在通义千问VLOCR模型中,图像转换为Token的规则:每28x28像素对应一个Token。即max_pixels的默认值为1280Token。

使用方法

  • 当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。

  • 当输入图像像素小于min_pixels时,会将图像按原比例放大,直到总像素高于min_pixels

  • 当输入图像像素大于max_pixels时,会将图像按原比例缩小,直到总像素低于max_pixels

role string (必选)

固定为user

Assistant Message object (可选)

模型对用户消息的回复。

属性

content string (可选)

消息内容。仅当助手消息中指定tool_calls参数时非必选。

role string (必选)

固定为assistant

partial boolean (可选)

是否开启Partial Mode。使用方法请参考Partial Mode

支持的模型

  • 通用文本模型

    qwen-max、qwen-max-0919、qwen-max-latest、qwen-plus、qwen-plus-1127、qwen-plus-1125、qwen-plus-0919、qwen-plus-latest、qwen-turbo、qwen-turbo-1101、qwen-turbo-0919、qwen-turbo-latestqwen2.5系列模型

  • 代码模型

    qwen-coder-plus、qwen-coder-plus-latest、qwen-coder-plus-2024-11-06 、qwen-coder-turbo、qwen-coder-turbo-latest、qwen-coder-turbo-2024-09-19qwen2.5-coder系列模型

  • 数学模型

    qwen-math-plus、qwen-math-plus-latest、qwen-math-plus-0919、qwen-math-turbo、qwen-math-turbo-latest、qwen-math-turbo-0919qwen2.5-math系列模型

tool_calls array (可选)

在发起 Function call后,模型回复的要调用的工具和调用工具时需要的参数。包含一个或多个对象。由上一轮模型响应的tool_calls字段获得。

属性

id string

本次工具响应的ID。

type string

工具的类型,当前只支持function

function object

需要被调用的函数。

属性

name string

需要被调用的函数名。

arguments string

需要输入到工具中的参数,为JSON字符串。

index integer

工具信息在tool_calls列表中的索引。

Tool Message object (可选)

工具的输出信息。详细说明:Function Call(工具调用)

属性

content string (必选)

消息内容,一般为工具函数的输出。

role string (必选)

固定为tool

stream boolean (可选) 默认值为 false

是否流式输出回复。参数值:

  • false:模型生成完所有内容后一次性返回结果。

  • true:边生成边输出,即每生成一部分内容就立即输出一个片段(chunk)。您需要实时地逐个读取这些片段以获得完整的结果。

stream_options object (可选)

当启用流式输出时,可通过将本参数设置为{"include_usage": true},在输出的最后一行显示所使用的Token数。

如果设置为false,则最后一行不显示使用的Token数。

本参数仅在设置streamtrue下生效。

temperature float (可选)

采样温度,控制模型生成文本的多样性。

temperature越高,生成的文本更多样,反之,生成的文本更确定。

取值范围: [0, 2)

由于temperaturetop_p均可以控制生成文本的多样性,因此建议您只设置其中一个值。更多说明,请参见Temperature 和 top_p

temperature默认值

qwen-max系列、qwen-plus系列、qwen-turbo系列以及qwen开源系列:0.7;

qwen-long:1.0;

qwen-vl-ocr:0.1;

qwen-vl系列:0.01;

qwen-audio系列:0.7;

qwen-math系列:0;

qwen-coder系列:0.7。

top_p float (可选)

核采样的概率阈值,控制模型生成文本的多样性。

top_p越高,生成的文本更多样。反之,生成的文本更确定。

取值范围:(0,1.0]

由于temperaturetop_p均可以控制生成文本的多样性,因此建议您只设置其中一个值。更多说明,请参见Temperature 和 top_p

top_p默认值

qwen-max系列、qwen-plus系列、qwen-turbo系列以及qwen开源系列:0.8;

qwen-long:0.8;

qwen-vl-ocr:0.01;

qwen-vl系列:0.001;

qwen-audio系列:0.5;

qwen-math系列:1.0;

qwen-coder系列:0.8。

presence_penalty float (可选)

控制模型生成文本时的内容重复度。

取值范围:[-2.0, 2.0]。正数会减少重复度,负数会增加重复度。

适用场景:

较高的presence_penalty适用于要求多样性、趣味性或创造性的场景,如创意写作或头脑风暴。

较低的presence_penalty适用于要求一致性或专业术语的场景,如技术文档或其他正式文档。

原理介绍

如果参数值是正数,模型将对目前文本中已存在的Token施加一个惩罚值(惩罚值与文本出现的次数无关),减少这些Token重复出现的几率,从而减少内容重复度,增加用词多样性。

示例

提示词:把这句话翻译成中文“This movie is good. The plot is good, the acting is good, the music is good, and overall, the whole movie is just good. It is really good, in fact. The plot is so good, and the acting is so good, and the music is so good.”

参数值为2.0:这部电影很好。剧情很棒,演技棒,音乐也非常好听,总的来说,整部电影都好得不得了。实际上它真的很优秀。剧情非常精彩,演技出色,音乐也是那么的动听。

参数值为0.0:这部电影很好。剧情好,演技好,音乐也好,总的来说,整部电影都很好。事实上,它真的很棒。剧情非常好,演技也非常出色,音乐也同样优秀。

参数值为-2.0:这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。

response_format object (可选) 默认值为{"type": "text"}

返回内容的格式。可选值:{"type": "text"}{"type": "json_object"}。设置为{"type": "json_object"}时会输出标准格式的JSON字符串。

如果指定该参数为{"type": "json_object"},您需要在System MessageUser Message中指引模型输出JSON格式,如:“请按照json格式输出。”
支持qwen-max、qwen-max-0919、qwen-max-latest、qwen-plus、qwen-plus-1127、qwen-plus-1125、qwen-plus-0919、qwen-plus-latest、qwen-turbo、qwen-turbo-1101、qwen-turbo-0919、qwen-turbo-latest以及qwen2.5系列模型(不包含mathcoder模型)。

max_tokens integer (可选)

本次请求返回的最大 Token 数。

max_tokens 的设置不会影响大模型的生成过程,如果模型生成的 Token 数超过max_tokens,本次请求会返回截断后的内容。

默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度,请参见模型列表

max_tokens参数适用于需要限制字数(如生成摘要、关键词)、控制成本或减少响应时间的场景。

n integer (可选) 默认值为1

生成响应的个数,取值范围是1-4。对于需要生成多个响应的场景(如创意写作、广告文案等),可以设置较大的 n 值。

当前仅支持 qwen-plus 模型,且在传入 tools 参数时固定为1。
设置较大的 n 值不会增加输入 Token 消耗,会增加输出 Token 的消耗。

seed integer (可选)

设置seed参数会使文本生成过程更具有确定性,通常用于使模型每次运行的结果一致。

在每次模型调用时传入相同的seed值(由您指定),并保持其他参数不变,模型将尽可能返回相同的结果。

取值范围:无符号64位整数,即0264−1。

stop string 或 array (可选)

使用stop参数后,当模型生成的文本即将包含指定的字符串或token_id时,将自动停止生成。

您可以在stop参数中传入敏感词来控制模型的输出。

stoparray类型时,不可以将token_id和字符串同时作为元素输入,比如不可以指定stop["你好",104307]

tools array (可选)

可供模型调用的工具数组,可以包含一个或多个工具对象。一次function call流程模型会从中选择一个工具。

目前不支持通义千问VL/Audio,也不建议用于数学和代码模型

属性

type string (必选)

tools的类型,当前仅支持function。

function object (必选)

属性

name string (必选)

工具函数的名称,必须是字母、数字,可以包含下划线和短划线,最大长度为64。

description string (必选)

工具函数的描述,供模型选择何时以及如何调用工具函数。

parameters object (必选)

工具的参数描述,需要是一个合法的JSON Schema。JSON Schema的描述可以见链接。如果parameters参数为空,表示function没有入参。

translation_options object (可选)

当您使用翻译模型时需要配置的翻译参数。

属性

source_lang string (必选)

源语言的英文全称,详情请参见支持的语言

targer_lang string (必选)

目标语言的英文全称,详情请参见支持的语言

terms arrays (可选)

在使用术语干预翻译功能时需要设置的术语数组。

属性

source string (必选)

源语言的术语。

target string (必选)

目标语言的术语。

tm_list arrays (可选)

使用翻译记忆功能时需要设置的翻译记忆数组。

属性

source string (必选)

源语言的语句。

target string (必选)

目标语言的语句。

domains string (可选)

在使用领域提示功能时需要设置的领域提示语句。

领域提示语句暂时只支持英文。
若您通过Python SDK调用,请通过extra_body配置。配置方式为:extra_body={"translation_options": xxx}

enable_search boolean (可选)

模型在生成文本时是否使用互联网搜索结果进行参考。取值如下:

  • true:启用互联网搜索,模型会将搜索结果作为文本生成过程中的参考信息,但模型会基于其内部逻辑判断是否使用互联网搜索结果。

    如果模型没有搜索互联网,建议优化Prompt。
  • false(默认):关闭互联网搜索。

启用互联网搜索功能可能会增加Token消耗。
若您通过 Python SDK调用,请通过extra_body配置。配置方式为:extra_body={"enable_search": true}
qwen-vl系列、qwen开源系列与qwen-long模型暂时不支持配置该参数。

chat响应对象(非流式输出)

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "我是阿里云开发的一款超大规模语言模型,我叫通义千问。"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 3019,
        "completion_tokens": 104,
        "total_tokens": 3123,
        "prompt_tokens_details": {
            "cached_tokens": 2048
        }
    },
    "created": 1735120033,
    "system_fingerprint": null,
    "model": "qwen-plus",
    "id": "chatcmpl-6ada9ed2-7f33-9de2-8bb0-78bd4035025a"
}

id string

本次调用的唯一标识符。

choices array

模型生成内容的数组,可以包含一个或多个choices对象。

属性

finish_reason string

有三种情况:

  • 因触发输入参数中的stop条件,或自然停止输出时为stop

  • 因生成长度过长而结束为length

  • 因需要调用工具而结束为tool_calls

index integer

当前响应在choices数组中的序列编号。

logprobs object

该参数当前固定为null

message object

本次调用模型输出的消息。

属性

content string

本次调用模型生成的文本。

refusal string

该参数当前固定为null

role string

消息的角色,固定为assistant

audio object

该参数当前固定为null

function_call(即将废弃)object

该值默认为null,请参考tool_calls参数。

tool_calls array

在发起 Function call后,模型回复的要调用的工具以及调用工具所需的参数。可以包含一个或多个工具响应对象。

属性

id string

本次工具响应的ID。

type string

工具的类型,当前只支持function

function object

需要被调用的函数。

属性

name string

需要被调用的函数名。

arguments string

需要输入到工具中的参数,为JSON字符串。

由于大模型响应有一定随机性,输出的JSON字符串并不总满足于您的函数,建议您在将参数输入函数前进行参数的有效性校验。

index integer

工具信息在tool_calls列表中的索引。

created integer

本次chat请求被创建时的时间戳。

model string

本次chat请求使用的模型名称。

object string

始终为chat.completion

service_tier string

该参数当前固定为null

system_fingerprint string

该参数当前固定为null

usage object

本次chat请求使用的Token信息。

属性

completion_tokens integer

模型生成回复转换为Token后的长度。

prompt_tokens integer

用户的输入转换成Token后的长度。

total_tokens integer

prompt_tokenscompletion_tokens的总和。

completion_tokens_details object

该参数当前固定为null

prompt_tokens_details object

输入 Token 的细粒度分类。

属性

audio_tokens integer

该参数当前固定为null

cached_tokens integer

命中 Cache 的 Token 数。Context Cache 详情请参见Context Cache(上下文缓存)

chat响应chunk对象(流式输出)

{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"我是","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"来自","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"阿里","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"云的超大规模","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"语言模型,我","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"叫通义千","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"问。","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-e30f5ae7-3063-93c4-90fe-beb5f900bd57","choices":[],"created":1735113344,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":{"completion_tokens":17,"prompt_tokens":22,"total_tokens":39,"completion_tokens_details":null,"prompt_tokens_details":{"audio_tokens":null,"cached_tokens":0}}}

id string

本次调用的唯一标识符。每个chunk对象有相同的id。

choices array

模型生成内容的数组,可包含一个或多个choices对象。如果设置include_usage参数为true,则最后一个chunk为空。

属性

delta object

chat请求的增量对象。

属性

content string

chunk的消息内容。

function_call object

该值默认为null,请参考tool_calls参数。

refusal object

该参数当前固定为null

role string

增量消息对象的角色,只在第一个chunk中有值。

tools_calls array

模型回复的要调用的工具以及调用工具所需的参数。可以包含一个或多个工具响应对象。

属性

index integer

工具信息在tool_calls列表中的索引。

id string

本次工具响应的ID。

function object

需要被调用的函数。

属性

arguments string

需要输入到工具中的参数,所有chunkarguments拼接后为完整的JSON字符串。

由于大模型响应有一定随机性,输出的JSON字符串并不总满足于您的函数,建议您在将参数输入函数前进行参数的有效性校验。

name string

函数名称,只在第一个chunk中有值。

type string

工具的类型,当前只支持function

finish_reason string

有四种情况:

  • 因触发输入参数中的stop条件,或自然停止输出时为stop

  • 当生成未结束时为null

  • 因生成长度过长而结束为length

  • 因需要调用工具而结束为tool_calls

index integer

当前响应在choices列表中的序列编号。当输入参数 n 大于1时,您需要根据 index 参数来进行不同响应对应的完整内容的拼接。

created integer

本次chat请求被创建时的时间戳。每个chunk对象有相同的时间戳。

model string

本次chat请求使用的模型名称。

object string

始终为chat.completion.chunk

service_tier string

该参数当前固定为null

system_fingerprintstring

该参数当前固定为null

usage object

本次chat请求使用的Token信息。只在include_usagetrue时,在最后一个chunk显示。

属性

completion_tokens integer

模型生成回复转换为Token后的长度。

prompt_tokens integer

用户的输入转换成Token后的长度。

total_tokens integer

prompt_tokenscompletion_tokens的总和。

completion_tokens_details object

该参数当前固定为null

prompt_tokens_details object

使用 Token 的细粒度分类。

属性

audio_tokens integer

该参数当前固定为null

cached_tokens integer

命中 Cache 的 Token 数。Context Cache 详情请参见Context Cache(上下文缓存)

DashScope

公有云

通过HTTP调用时需配置的endpoint:

使用通义千问大语言模型:POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation

使用通义千问VL或通义千问Audio模型:POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

金融云

  • 通过HTTP调用时需配置的endpoint:

    使用通义千问大语言模型:POST https://dashscope-finance.aliyuncs.com/api/v1/services/aigc/text-generation/generation

  • 通过SDK调用时需配置的base_url:https://dashscope-finance.aliyuncs.com/api/v1

    Python:在导入模块之后,添加以下代码:

    dashscope.base_http_api_url = 'https://dashscope-finance.aliyuncs.com/api/v1'

    Java :将Generation gen = new Generation();修改为

    Generation gen = new Generation("http", "https://dashscope-finance.aliyuncs.com/api/v1");
您需要已获取API Key配置API Key到环境变量。如果通过DashScope SDK进行调用,还需要安装DashScope SDK

请求体

文本输入

Python

import os
import dashscope

messages = [
    {'role': 'system', 'content': 'You are a helpful assistant.'},
    {'role': 'user', 'content': '你是谁?'}
    ]
response = dashscope.Generation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus", # 模型列表:https://help.aliyun.com/zh/model-studio/getting-started/models
    messages=messages,
    result_format='message'
    )
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("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .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);
    }
}

HTTP

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": "qwen-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你是谁?"
            }
        ]
    },
    "parameters": {
        "result_format": "message"
    }
}'

PHP

<?php

$url = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation";
$apiKey = getenv('DASHSCOPE_API_KEY');

$data = [
    "model" => "qwen-plus",
    "input" => [
        "messages" => [
            [
                "role" => "system",
                "content" => "You are a helpful assistant."
            ],
            [
                "role" => "user",
                "content" => "你是谁?"
            ]
        ]
    ],
    "parameters" => [
        "result_format" => "message"
    ]
];

$jsonData = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Authorization: Bearer $apiKey",
    "Content-Type: application/json"
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($httpCode == 200) {
    echo "Response: " . $response;
} else {
    echo "Error: " . $httpCode . " - " . $response;
}

curl_close($ch);
?>

Node.js

DashScope 未提供 Node.js 环境的 SDK。如需通过 OpenAI Node.js SDK调用,请参考本文的OpenAI章节。

import fetch from 'node-fetch';

const apiKey = process.env.DASHSCOPE_API_KEY;

const data = {
    model: "qwen-plus",
    input: {
        messages: [
            {
                role: "system",
                content: "You are a helpful assistant."
            },
            {
                role: "user",
                content: "你是谁?"
            }
        ]
    },
    parameters: {
        result_format: "message"
    }
};

fetch('https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${apiKey}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify(data)
})
.then(response => response.json())
.then(data => {
    console.log(JSON.stringify(data));
})
.catch(error => {
    console.error('Error:', error);
});

C#

using System.Net.Http.Headers;
using System.Text;

class Program
{
    private static readonly HttpClient httpClient = new HttpClient();

    static async Task Main(string[] args)
    {
        // 若没有配置环境变量,请用百炼API Key将下行替换为:string? apiKey = "sk-xxx";
        string? apiKey = Environment.GetEnvironmentVariable("DASHSCOPE_API_KEY");

        if (string.IsNullOrEmpty(apiKey))
        {
            Console.WriteLine("API Key 未设置。请确保环境变量 'DASHSCOPE_API_KEY' 已设置。");
            return;
        }

        // 设置请求 URL 和内容
        string url = "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation";
        string jsonContent = @"{
            ""model"": ""qwen-plus"",
            ""input"": {
                ""messages"": [
                    {
                        ""role"": ""system"",
                        ""content"": ""You are a helpful assistant.""
                    },
                    {
                        ""role"": ""user"",
                        ""content"": ""你是谁?""
                    }
                ]
            },
            ""parameters"": {
                ""result_format"": ""message""
            }
        }";

        // 发送请求并获取响应
        string result = await SendPostRequestAsync(url, jsonContent, apiKey);

        // 输出结果
        Console.WriteLine(result);
    }

    private static async Task<string> SendPostRequestAsync(string url, string jsonContent, string apiKey)
    {
        using (var content = new StringContent(jsonContent, Encoding.UTF8, "application/json"))
        {
            // 设置请求头
            httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
            httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

            // 发送请求并获取响应
            HttpResponseMessage response = await httpClient.PostAsync(url, content);

            // 处理响应
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }
            else
            {
                return $"请求失败: {response.StatusCode}";
            }
        }
    }
}

Go

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

type Message struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type Input struct {
	Messages []Message `json:"messages"`
}

type Parameters struct {
	ResultFormat string `json:"result_format"`
}

type RequestBody struct {
	Model      string     `json:"model"`
	Input      Input      `json:"input"`
	Parameters Parameters `json:"parameters"`
}

func main() {
	// 创建 HTTP 客户端
	client := &http.Client{}

	// 构建请求体
	requestBody := RequestBody{
		Model: "qwen-plus",
		Input: Input{
			Messages: []Message{
				{
					Role:    "system",
					Content: "You are a helpful assistant.",
				},
				{
					Role:    "user",
					Content: "你是谁?",
				},
			},
		},
		Parameters: Parameters{
			ResultFormat: "message",
		},
	}

	jsonData, err := json.Marshal(requestBody)
	if err != nil {
		log.Fatal(err)
	}

	// 创建 POST 请求
	req, err := http.NewRequest("POST", "https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation", bytes.NewBuffer(jsonData))
	if err != nil {
		log.Fatal(err)
	}

	// 设置请求头
	// 若没有配置环境变量,请用百炼API Key将下行替换为:apiKey := "sk-xxx"
	apiKey := os.Getenv("DASHSCOPE_API_KEY")
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	// 发送请求
	resp, err := client.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	// 读取响应体
	bodyText, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}

	// 打印响应内容
	fmt.Printf("%s\n", bodyText)
}

Java

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;

import com.google.gson.Gson;

public class Main {

    static class Message {
        String role;
        String content;

        public Message(String role, String content) {
            this.role = role;
            this.content = content;
        }
    }

    static class Input {
        Message[] messages;

        public Input(Message[] messages) {
            this.messages = messages;
        }
    }

    static class Parameters {
        String result_format;

        public Parameters(String result_format) {
            this.result_format = result_format;
        }
    }

    static class RequestBody {
        String model;
        Input input;
        Parameters parameters;

        public RequestBody(String model, Input input, Parameters parameters) {
            this.model = model;
            this.input = input;
            this.parameters = parameters;
        }
    }

    public static void main(String[] args) {
        try {
            // 创建请求体
            RequestBody requestBody = new RequestBody(
                    "qwen-plus",
                    new Input(new Message[] {
                            new Message("system", "You are a helpful assistant."),
                            new Message("user", "你是谁?")
                    }),
                    new Parameters("message")
            );

            // 将请求体转换为 JSON
            Gson gson = new Gson();
            String jsonInputString = gson.toJson(requestBody);

            // 创建 URL 对象
            URL url = new URL("https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation");
            HttpURLConnection httpURLConnection = (HttpURLConnection) url.openConnection();

            // 设置请求方法为 POST
            httpURLConnection.setRequestMethod("POST");
            httpURLConnection.setRequestProperty("Content-Type", "application/json; utf-8");
            httpURLConnection.setRequestProperty("Accept", "application/json");

            // 若没有配置环境变量,请用百炼API Key将下行替换为:String apiKey = "sk-xxx";
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            String auth = "Bearer " + apiKey;
            httpURLConnection.setRequestProperty("Authorization", auth);

            // 启用输入输出流
            httpURLConnection.setDoOutput(true);

            // 写入请求体
            try (OutputStream os = httpURLConnection.getOutputStream()) {
                byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }

            // 读取响应体
            try (BufferedReader br = new BufferedReader(new InputStreamReader(httpURLConnection.getInputStream(), StandardCharsets.UTF_8))) {
                StringBuilder response = new StringBuilder();
                String responseLine;
                while ((responseLine = br.readLine()) != null) {
                    response.append(responseLine.trim());
                }
                System.out.println(response);
            }

        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            System.exit(0);
        }
    }
}

流式输出

Python

import os
import dashscope

messages = [
    {'role':'system','content':'you are a helpful assistant'},
    {'role': 'user','content': '你是谁?'}
    ]
responses = dashscope.Generation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus",
    messages=messages,
    result_format='message',
    stream=True,
    incremental_output=True
    )
for response in responses:
    print(response)  

Java

import java.util.Arrays;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
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;
import io.reactivex.Flowable;
import java.lang.System;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    private static void handleGenerationResult(GenerationResult message) {
        System.out.println(JsonUtils.toJson(message));
    }
    public static void streamCallWithMessage(Generation gen, Message userMsg)
            throws NoApiKeyException, ApiException, InputRequiredException {
        GenerationParam param = buildGenerationParam(userMsg);
        Flowable<GenerationResult> result = gen.streamCall(param);
        result.blockingForEach(message -> handleGenerationResult(message));
    }
    private static GenerationParam buildGenerationParam(Message userMsg) {
        return GenerationParam.builder()
                // 若没有配置环境变量,请用百炼API Key将下行替换为:.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(Arrays.asList(userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .incrementalOutput(true)
                .build();
    }
    public static void main(String[] args) {
        try {
            Generation gen = new Generation();
            Message userMsg = Message.builder().role(Role.USER.getValue()).content("你是谁?").build();
            streamCallWithMessage(gen, userMsg);
        } catch (ApiException | NoApiKeyException | InputRequiredException  e) {
            logger.error("An exception occurred: {}", e.getMessage());
        }
        System.exit(0);
    }
}

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" \
--header "X-DashScope-SSE: enable" \
--data '{
    "model": "qwen-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "你是谁?"
            }
        ]
    },
    "parameters": {
        "result_format": "message",
        "incremental_output":true
    }
}'

图像输入

关于大模型分析图像的更多用法,请参考:视觉理解

Python

import os
import dashscope

messages = [
    {
        "role": "user",
        "content": [
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"},
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},
            {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"},
            {"text": "这些是什么?"}
        ]
    }
]
response = dashscope.MultiModalConversation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen-vl-max',
    messages=messages
    )
print(response)

Java

// Copyright (c) Alibaba, Inc. and its affiliates.

import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"),
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"),
                        Collections.singletonMap("image", "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"),
                        Collections.singletonMap("text", "这些是什么?"))).build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // 若没有配置环境变量,请用百炼API Key将下行替换为:.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-vl-plus")
                .message(userMessage)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen-vl-plus",
    "input":{
        "messages":[
            {
                "role": "user",
                "content": [
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog_and_girl.jpeg"},
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/tiger.png"},
                    {"image": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/rabbit.png"},
                    {"text": "这些是什么?"}
                ]
            }
        ]
    }
}'

视频输入

关于大模型分析视频的更多用法,请参考:视觉理解

Python

from http import HTTPStatus
import os
# dashscope版本需要不低于1.20.10
import dashscope

messages = [{"role": "user",
             "content": [
                 {"video":["https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
                           "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
                           "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
                           "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg"]},
                 {"text": "描述这个视频的具体过程"}]}]
response = dashscope.MultiModalConversation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    model='qwen-vl-max-latest',
    messages=messages
)
if response.status_code == HTTPStatus.OK:
    print(response)
else:
    print(response.code)
    print(response.message)

Java

// DashScope SDK版本需要不低于2.16.7
import java.util.Arrays;
import java.util.Collections;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
    private static final String MODEL_NAME = "qwen-vl-max-latest";
    public static void videoImageListSample() throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage systemMessage = MultiModalMessage.builder()
                .role(Role.SYSTEM.getValue())
                .content(Arrays.asList(Collections.singletonMap("text", "You are a helpful assistant.")))
                .build();
        MultiModalMessage userMessage = MultiModalMessage.builder()
                .role(Role.USER.getValue())
                .content(Arrays.asList(Collections.singletonMap("video", Arrays.asList("https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
                                "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
                                "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
                                "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg")),
                        Collections.singletonMap("text", "描述这个视频的具体过程")))
                .build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                .model(MODEL_NAME).message(systemMessage)
                .message(userMessage).build();
        MultiModalConversationResult result = conv.call(param);
        System.out.print(JsonUtils.toJson(result));
    }
    public static void main(String[] args) {
        try {
            videoImageListSample();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
  "model": "qwen-vl-max-latest",
  "input": {
    "messages": [
      {
        "role": "user",
        "content": [
          {
            "video": [
              "https://img.alicdn.com/imgextra/i3/O1CN01K3SgGo1eqmlUgeE9b_!!6000000003923-0-tps-3840-2160.jpg",
              "https://img.alicdn.com/imgextra/i4/O1CN01BjZvwg1Y23CF5qIRB_!!6000000003000-0-tps-3840-2160.jpg",
              "https://img.alicdn.com/imgextra/i4/O1CN01Ib0clU27vTgBdbVLQ_!!6000000007859-0-tps-3840-2160.jpg",
              "https://img.alicdn.com/imgextra/i1/O1CN01aygPLW1s3EXCdSN4X_!!6000000005710-0-tps-3840-2160.jpg"
            ]
          },
          {
            "text": "描述这个视频的具体过程"
          }
        ]
      }
    ]
  }
}'

音频输入

关于大模型分析音频的更多用法,请参考:音频理解

Python

import os
import dashscope

messages = [
    {
        "role": "user",
        "content": [
            {"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"},
            {"text": "这段音频在说什么?"}
        ]
    }
]
response = dashscope.MultiModalConversation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen2-audio-instruct',
    messages=messages
    )
print(response)

Java

import java.util.Arrays;
import java.util.Collections;
import java.lang.System;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(Collections.singletonMap("audio", "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"),
                        Collections.singletonMap("text", "这段音频在说什么?"))).build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // 若没有配置环境变量,请用百炼API Key将下行替换为:.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen2-audio-instruct")
                .message(userMessage)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen2-audio-instruct",
    "input":{
        "messages":[
            {
                "role": "system",
                "content": [
                    {"text": "You are a helpful assistant."}
                ]
            },
            {
                "role": "user",
                "content": [
                    {"audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/audios/welcome.mp3"},
                    {"text": "这段音频在说什么?"}
                ]
            }
        ]
    }
}'

联网搜索

Python

import os
import dashscope

messages = [
    {'role': 'system', 'content': 'You are a helpful assistant.'},
    {'role': 'user', 'content': '杭州明天天气是什么?'}
    ]
response = dashscope.Generation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model="qwen-plus",
    messages=messages,
    enable_search=True,
    result_format='message'
    )
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("qwen-plus")
                .messages(Arrays.asList(systemMsg, userMsg))
                .resultFormat(GenerationParam.ResultFormat.MESSAGE)
                .enableSearch(true)
                .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);
    }
}

curl

curl -X POST https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-plus",
    "input":{
        "messages":[      
            {
                "role": "system",
                "content": "You are a helpful assistant."
            },
            {
                "role": "user",
                "content": "明天杭州天气如何?"
            }
        ]
    },
    "parameters": {
        "enable_search": true,
        "result_format": "message"
    }
}'

工具调用

完整的Function Call流程代码请参考:Function Call(工具调用)

Python

import os
import dashscope

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "当你想知道现在的时间时非常有用。",
            "parameters": {}
        }
    },  
    {
        "type": "function",
        "function": {
            "name": "get_current_weather",
            "description": "当你想查询指定城市的天气时非常有用。",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                    }
                }
            },
            "required": [
                "location"
            ]
        }
    }
]
messages = [{"role": "user", "content": "杭州天气怎么样"}]
response = dashscope.Generation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen-plus',
    messages=messages,
    tools=tools,
    result_format='message'
)
print(response)

Java

import java.util.ArrayList;
import java.util.Arrays;
import java.util.List;
import com.alibaba.dashscope.aigc.conversation.ConversationParam.ResultFormat;
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.tools.FunctionDefinition;
import com.alibaba.dashscope.tools.ToolFunction;
import com.alibaba.dashscope.utils.JsonUtils;
import com.fasterxml.jackson.databind.node.ObjectNode;
import com.github.victools.jsonschema.generator.Option;
import com.github.victools.jsonschema.generator.OptionPreset;
import com.github.victools.jsonschema.generator.SchemaGenerator;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfig;
import com.github.victools.jsonschema.generator.SchemaGeneratorConfigBuilder;
import com.github.victools.jsonschema.generator.SchemaVersion;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

public class Main {
    public class GetWeatherTool {
        private String location;
        public GetWeatherTool(String location) {
            this.location = location;
        }
        public String call() {
            return location+"今天是晴天";
        }
    }
    public class GetTimeTool {
        public GetTimeTool() {
        }
        public String call() {
            LocalDateTime now = LocalDateTime.now();
            DateTimeFormatter formatter = DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss");
            String currentTime = "当前时间:" + now.format(formatter) + "。";
            return currentTime;
        }
    }
    public static void SelectTool()
            throws NoApiKeyException, ApiException, InputRequiredException {
        SchemaGeneratorConfigBuilder configBuilder =
                new SchemaGeneratorConfigBuilder(SchemaVersion.DRAFT_2020_12, OptionPreset.PLAIN_JSON);
        SchemaGeneratorConfig config = configBuilder.with(Option.EXTRA_OPEN_API_FORMAT_VALUES)
                .without(Option.FLATTENED_ENUMS_FROM_TOSTRING).build();
        SchemaGenerator generator = new SchemaGenerator(config);
        ObjectNode jsonSchema_weather = generator.generateSchema(GetWeatherTool.class);
        ObjectNode jsonSchema_time = generator.generateSchema(GetTimeTool.class);
        FunctionDefinition fdWeather = FunctionDefinition.builder().name("get_current_weather").description("获取指定地区的天气")
                .parameters(JsonUtils.parseString(jsonSchema_weather.toString()).getAsJsonObject()).build();
        FunctionDefinition fdTime = FunctionDefinition.builder().name("get_current_time").description("获取当前时刻的时间")
                .parameters(JsonUtils.parseString(jsonSchema_time.toString()).getAsJsonObject()).build();
        Message systemMsg = Message.builder().role(Role.SYSTEM.getValue())
                .content("You are a helpful assistant. When asked a question, use tools wherever possible.")
                .build();
        Message userMsg = Message.builder().role(Role.USER.getValue()).content("杭州天气").build();
        List<Message> messages = new ArrayList<>();
        messages.addAll(Arrays.asList(systemMsg, userMsg));
        GenerationParam param = GenerationParam.builder()
                // 若没有配置环境变量,请用百炼API Key将下行替换为:.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-plus")
                .messages(messages)
                .resultFormat(ResultFormat.MESSAGE)
                .tools(Arrays.asList(
                        ToolFunction.builder().function(fdWeather).build(),
                        ToolFunction.builder().function(fdTime).build()))
                .build();
        Generation gen = new Generation();
        GenerationResult result = gen.call(param);
        System.out.println(JsonUtils.toJson(result));
    }
    public static void main(String[] args) {
        try {
            SelectTool();
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.out.println(String.format("Exception %s", e.getMessage()));
        }
        System.exit(0);
    }
}

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": "qwen-plus",
    "input": {
        "messages": [{
            "role": "user",
            "content": "杭州天气怎么样"
        }]
    },
    "parameters": {
        "result_format": "message",
        "tools": [{
            "type": "function",
            "function": {
                "name": "get_current_time",
                "description": "当你想知道现在的时间时非常有用。",
                "parameters": {}
            }
        },{
            "type": "function",
            "function": {
                "name": "get_current_weather",
                "description": "当你想查询指定城市的天气时非常有用。",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "城市或县区,比如北京市、杭州市、余杭区等。"
                        }
                    }
                },
                "required": ["location"]
            }
        }]
    }
}'

异步调用

# 您的Dashscope Python SDK版本需要不低于 1.19.0。
import asyncio
import platform
import os
from dashscope.aigc.generation import AioGeneration

async def main():
    response = await AioGeneration.call(
        # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
        api_key=os.getenv('DASHSCOPE_API_KEY'),
        model="qwen-plus",
        messages=[{"role": "user", "content": "你是谁"}],
        result_format="message",
    )
    print(response)

if platform.system() == "Windows":
    asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
asyncio.run(main())

文字提取

qwen-vl-ocrOCR专用模型。为保证模型效果,目前模型内部会采用固定的文本作为输入文本,用户自定义的文本不会生效。关于qwen-vl-ocr的更多用法,请参见文字提取(OCR)

Python

import os
import dashscope

messages = [{
            "role": "user",
            "content": [{
                "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg",
                "min_pixels": 28 * 28 * 4,
                "max_pixels": 1280 * 784},
                # 目前为保证模型效果,模型内部会统一使用"Read all the text in the image."作为text的值,用户输入的文本不会生效。
                {"type": "text", "text": "Read all the text in the image."}]
        }]
response = dashscope.MultiModalConversation.call(
    # 若没有配置环境变量,请用百炼API Key将下行替换为:api_key="sk-xxx",
    api_key=os.getenv('DASHSCOPE_API_KEY'),
    model='qwen-vl-ocr',
    messages=messages,
    top_p=0.01,
    temperature=0.1,
    max_tokens=2000)
print(response)  

Java

import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
import java.util.HashMap;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.common.MultiModalMessage;
import com.alibaba.dashscope.common.Role;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
public class Main {
    public static void simpleMultiModalConversationCall()
            throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        Map<String, Object> map = new HashMap<>();
        map.put("image", "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg");
        map.put("max_pixels", "1003520");
        map.put("min_pixels", "3136");
        MultiModalMessage userMessage = MultiModalMessage.builder().role(Role.USER.getValue())
                .content(Arrays.asList(
                        map,
                        // 目前为保证模型效果,模型内部会统一使用"Read all the text in the image."作为text的值,用户输入的文本不会生效。
                        Collections.singletonMap("text", "Read all the text in the image."))).build();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // 若没有配置环境变量,请用百炼API Key将下行替换为:.apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model("qwen-vl-ocr")
                .message(userMessage)
                .topP(0.01)
                .temperature(0.1f)
                .maxLength(2000)
                .build();
        MultiModalConversationResult result = conv.call(param);
        System.out.println(JsonUtils.toJson(result));
    }

    public static void main(String[] args) {
        try {
            simpleMultiModalConversationCall();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

curl

curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen-vl-ocr",
    "input":{
        "messages":[
          {
            "role": "user",
            "content": [
                {
                    "image": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20241108/ctdzex/biaozhun.jpg",
                    "min_pixels": 3136,
                    "max_pixels": 1003520
                },
                {"type": "text", "text": "Read all the text in the image."}
            ]
          }
        ]
    },
    "parameters": {
        "top_p": 0.01,
        "temperature": 0.1,
        "repetition_penalty": 1.05,
        "max_tokens":2000
    }
}'

model string (必选)

模型名称。

支持的模型:通义千问大语言模型(商业版、开源版、Qwen-Long)、通义千问VL、通义千问Audio、数学模型、代码模型

具体模型名称和计费,请参见模型列表

messages array (必选)

由历史对话组成的消息列表。

通过HTTP调用时,请将messages 放入 input 对象中。

消息类型

System Message object

模型的目标或角色。如果设置系统消息,请放在messages列表的第一位。

属性

content string (必选)

消息内容。

role string (必选)

固定为system

User Message object

用户发送给模型的消息。

属性

content string 或 array (必选)

用户消息的内容。使用qwen 大语言模型时为string,使用qwen-vlqwen-audio系列模型时为array。

属性

text string

传入的文本信息。

image string

模型为视觉理解类模型时,是必选参数,如模型为qwen-vl-max、qwen-vl-plus等。

使用图片理解功能时,传入的图片文件。可以为图片的URL或本地路径信息。传入本地文件请参考使用本地文件

示例值:{"image":"https://xxxx.jpeg"}

video array

模型为视觉理解类模型时,是必选参数,如模型为qwen-vl-max、qwen-vl-plus等。

使用视频理解功能时,传入的视频文件。您可以通过图片列表传入。

示例值:{"video":["https://xx1.jpg","https://xx2.jpg"]}

如果您需要直接输入视频文件,请提交工单进行申请以及获取使用方式。

audio string

模型为音频理解类模型时,是必选参数,如模型为qwen2-audio-instruct等。

使用音频理解功能时,传入的音频文件。

示例值:{"audio":"https://xxx.mp3"}

min_pixels integer (可选)

仅适用于通义千问OCR模型。

输入图像的最小像素。

默认值:3136(28*28*4)。

最小值:10*10。

在通义千问VLOCR模型中,图像转换为Token的规则:每28x28像素对应一个Token。即min_pixels的默认值为4Token。

使用方法

  • 当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。

  • 当输入图像像素小于min_pixels时,会将图像按原比例放大,直到总像素高于min_pixels

  • 当输入图像像素大于max_pixels时,会将图像按原比例缩小,直到总像素低于max_pixels

max_pixels integer (可选)

仅适用于通义千问OCR模型。

输入图像的最大像素。

默认值:1003520(28*28*1280)。

最大值:28*28*30000。

在通义千问VLOCR模型中,图像转换为Token的规则:每28x28像素对应一个Token。即max_pixels的默认值为1280Token。

使用方法

  • 当输入图像像素在[min_pixels, max_pixels]区间内时,模型会按原图进行识别。

  • 当输入图像像素小于min_pixels时,会将图像按原比例放大,直到总像素高于min_pixels

  • 当输入图像像素大于max_pixels时,会将图像按原比例缩小,直到总像素低于max_pixels

role string (必选)

用户消息的角色,固定为user

Assistant Message object

模型对用户消息的回复。

属性

content string (必选)

助手消息的内容。

role string (必选)

助手消息的角色,固定为assistant

partial boolean (可选)

是否开启Partial Mode。使用方法请参考Partial Mode

支持的模型

  • 通用文本模型

    qwen-max、qwen-max-0919、qwen-max-latest、qwen-plus、qwen-plus-0919、qwen-plus-latest、qwen-turbo、qwen-turbo-1101、qwen-turbo-0919、qwen-turbo-latestqwen2.5系列模型

  • 代码模型

    qwen-coder-plus、qwen-coder-plus-latest、qwen-coder-plus-2024-11-06 、qwen-coder-turbo、qwen-coder-turbo-latest、qwen-coder-turbo-2024-09-19qwen2.5-coder系列模型

  • 数学模型

    qwen-math-plus、qwen-math-plus-latest、qwen-math-plus-0919、qwen-math-turbo、qwen-math-turbo-latest、qwen-math-turbo-0919qwen2.5-math系列模型

Tool Message object

工具的输出信息。详细说明:Function Call(工具调用)

属性

content string (必选)

工具消息的内容,一般为工具函数的输出。

role string (必选)

工具消息的角色,固定为tool

temperature float (可选)

采样温度,控制模型生成文本的多样性。

temperature越高,生成的文本更多样,反之,生成的文本更确定。

取值范围: [0, 2)

通过HTTP调用时,请将 temperature 放入 parameters 对象中。

temperature默认值

  • qwen-max系列、qwen-plus系列、qwen-turbo系列以及qwen开源系列:0.7;

  • qwen-long:1.0;

  • qwen-vl-ocr:0.1;

  • qwen-vl系列:0.01;

  • qwen-audio系列:0.7;

  • qwen-math系列:0;

  • qwen-coder系列:0.7。

top_p float (可选)

核采样的概率阈值,控制模型生成文本的多样性。

top_p越高,生成的文本更多样。反之,生成的文本更确定。

取值范围:(0,1.0]。

Java SDK中为topP通过HTTP调用时,请将 top_p 放入 parameters 对象中。

top_p默认值

  • qwen-max系列、qwen-plus系列、qwen-turbo系列以及qwen开源系列:0.8;

  • qwen-long:0.8;

  • qwen-vl-ocr:0.01;

  • qwen-vl系列:0.001;

  • qwen-audio系列:0.5;

  • qwen-math系列:1.0;

  • qwen-coder系列:0.8。

top_k integer (可选)

生成过程中采样候选集的大小。例如,取值为50时,仅将单次生成中得分最高的50Token组成随机采样的候选集。取值越大,生成的随机性越高;取值越小,生成的确定性越高。取值为None或当top_k大于100时,表示不启用top_k策略,此时仅有top_p策略生效。

Java SDK中为topK通过HTTP调用时,请将 top_k 放入 parameters 对象中。

repetition_penalty float (可选)

模型生成时连续序列中的重复度。提高repetition_penalty时可以降低模型生成的重复度,1.0表示不做惩罚。没有严格的取值范围,只要大于0即可。

Java SDK中为repetitionPenalty通过HTTP调用时,请将 repetition_penalty 放入 parameters 对象中。
对于qwen-vl-ocr模型,repetition_penalty 的默认值为1.05,该参数对模型效果影响较大,请勿随意修改。

vl_high_resolution_images boolean (可选)默认值为 false

是否提高输入图片的默认Token上限,只适用于qwen-vl-maxqwen-vl-max-latestqwen-vl-max-0809qwen-vl-plus-latestqwen-vl-plus-0809模型。输入图片的默认Token上限为1280,配置为true时输入图片的Token上限为16384。

Java SDK不支持设置该参数通过HTTP调用时,请将 vl_high_resolution_images 放入 parameters 对象中。

presence_penalty float (可选)

控制模型生成文本时的内容重复度。

取值范围:[-2.0, 2.0]。正数会减少重复度,负数会增加重复度。

适用场景:

较高的presence_penalty适用于要求多样性、趣味性或创造性的场景,如创意写作或头脑风暴。

较低的presence_penalty适用于要求一致性或专业术语的场景,如技术文档或其他正式文档。

原理介绍

如果参数值是正数,模型将对目前文本中已存在的Token施加一个惩罚值(惩罚值与文本出现的次数无关),减少这些Token重复出现的几率,从而减少内容重复度,增加用词多样性。

示例

提示词:把这句话翻译成中文“This movie is good. The plot is good, the acting is good, the music is good, and overall, the whole movie is just good. It is really good, in fact. The plot is so good, and the acting is so good, and the music is so good.”

参数值为2.0:这部电影很好。剧情很棒,演技棒,音乐也非常好听,总的来说,整部电影都好得不得了。实际上它真的很优秀。剧情非常精彩,演技出色,音乐也是那么的动听。

参数值为0.0:这部电影很好。剧情好,演技好,音乐也好,总的来说,整部电影都很好。事实上,它真的很棒。剧情非常好,演技也非常出色,音乐也同样优秀。

参数值为-2.0:这部电影很好。情节很好,演技很好,音乐也很好,总的来说,整部电影都很好。实际上,它真的很棒。情节非常好,演技也非常好,音乐也非常好。

Java SDK不支持设置该参数通过HTTP调用时,请将 presence_penalty 放入 parameters 对象中。

max_tokens integer (可选)

本次请求返回的最大 Token 数。

max_tokens 的设置不会影响大模型的生成过程,如果模型生成的 Token 数超过max_tokens,本次请求会返回截断后的内容。

默认值和最大值都是模型的最大输出长度。关于各模型的最大输出长度,请参见模型列表

max_tokens参数适用于需要限制字数(如生成摘要、关键词)、控制成本或减少响应时间的场景。

Java SDK中为maxTokens通过HTTP调用时,请将 max_tokens 放入 parameters 对象中。

seed integer (可选)

设置seed参数会使文本生成过程更具有确定性,通常用于使模型每次运行的结果一致。

在每次模型调用时传入相同的seed值(由您指定),并保持其他参数不变,模型将尽可能返回相同的结果。

取值范围:无符号64位整数,即0264−1。

通过HTTP调用时,请将 seed 放入 parameters 对象中。

stream boolean (可选)

是否流式输出回复。参数值:

  • false(默认值):模型生成完所有内容后一次性返回结果。

  • true:边生成边输出,即每生成一部分内容就立即输出一个片段(chunk)。

该参数仅支持Python SDK。通过Java SDK实现流式输出请通过streamCall接口调用;通过HTTP实现流式输出请在Header中指定X-DashScope-SSEenable

incremental_output boolean (可选)默认为false

在流式输出模式下是否开启增量输出。参数值:

  • false:每次输出为当前已经生成的整个序列,最后一次输出为生成的完整结果。

    I
    I like
    I like apple
    I like apple.
  • true:增量输出,即后续输出内容不包含已输出的内容。您需要实时地逐个读取这些片段以获得完整的结果。

    I
    like
    apple
    .
Java SDK中为incrementalOutput通过HTTP调用时,请将 incremental_output 放入 parameters 对象中。

result_format string (可选)

返回结果的格式,默认为text,也可选择message。推荐您优先使用message格式。

Java SDK中为resultFormat通过HTTP调用时,请将 result_format 放入 parameters 对象中。

stop string 或 array (可选)

使用stop参数后,当模型生成的文本即将包含指定的字符串或token_id时,将自动停止生成。

您可以在stop参数中传入敏感词来控制模型的输出。

stoparray类型时,不可以将token_id和字符串同时作为元素输入,比如不可以指定stop["你好",104307]

tools array (可选)

可供模型调用的工具数组,可以包含一个或多个工具对象。一次function call流程模型会从中选择其中一个工具。使用tools时需要同时指定result_format参数为message。在function call流程中,无论是发起function call,还是向模型提交工具函数的执行结果,均需设置tools参数。

目前不支持通义千问VL/Audio,也不建议用于数学和代码模型

属性

type string (必选)

tools的类型,当前仅支持function。

function object (必选)

属性

name string (必选)

工具函数的名称,必须是字母、数字,可以包含下划线和短划线,最大长度为64。

description string (必选)

工具函数的描述,供模型选择何时以及如何调用工具函数。

parameters objcet (必选)

工具的参数描述,需要是一个合法的JSON Schema。JSON Schema的描述可以见链接。如果parameters参数为空,表示function没有入参。

通过HTTP调用时,请将 tools 放入 parameters JSON 对象中。暂时不支持qwen-vlqwen-audio系列模型。

tool_choice string 或 object (可选)

在使用tools参数时,用于控制模型调用指定工具。有三种取值:

  • "none"表示不调用工具。tools参数为空时,默认值为"none"

  • "auto"表示由模型判断是否调用工具,可能调用也可能不调用。tools参数不为空时,默认值为"auto"

  • object结构可以指定模型调用的工具。例如tool_choice={"type": "function", "function": {"name": "user_function"}}

    • type只支持指定为"function"

    • function

      • name表示期望被调用的工具名称,例如"get_current_time"

Java SDK中为toolChoice通过HTTP调用时,请将 tool_choice 放入 parameters 对象中。

translation_options object (可选)

当您使用翻译模型时需要配置的翻译参数。

属性

source_lang string (必选)

源语言的英文全称,详情请参见支持的语言

targer_lang string (必选)

目标语言的英文全称,详情请参见支持的语言

terms arrays (可选)

在使用术语干预翻译功能时需要设置的术语数组。

属性

source string (必选)

源语言的术语。

target string (必选)

目标语言的术语。

tm_list arrays (可选)

使用翻译记忆功能时需要设置的翻译记忆数组。

属性

source string (必选)

源语言的语句。

target string (必选)

目标语言的语句。

domains string (可选)

在使用领域提示功能时需要设置的领域提示语句。

领域提示语句暂时只支持英文。
Java SDK 暂不支持配置该参数。通过HTTP调用时,请将 translation_options 放入 parameters 对象中。

enable_search boolean (可选)

模型在生成文本时是否使用互联网搜索结果进行参考。取值如下:

  • true:启用互联网搜索,模型会将搜索结果作为文本生成过程中的参考信息,但模型会基于其内部逻辑判断是否使用互联网搜索结果。

    如果模型没有搜索互联网,建议优化Prompt。
  • false(默认):关闭互联网搜索。

若您的业务场景中需要使用互联网搜索能力,请配置该参数为true。

Java SDK中为enableSearch通过HTTP调用时,请将 enable_search 放入 parameters 对象中。
由于启用互联网搜索功能可能会增加token消耗,因此若您无需互联网搜索能力,不建议配置该参数。
qwen-vl系列、qwen-audio系列、qwen开源系列与qwen-long模型暂时不支持配置该参数。

search_options object (可选)

联网搜索的策略。仅当enable_searchtrue时生效。

支持的模型:qwen-max、qwen-plus、qwen-turbo。通过HTTP调用时,请将 enable_search 放入 parameters 对象中。该参数不支持通过Java SDK指定。

属性

enable_source boolean(可选)默认值为false

在返回结果中是否展示搜索到的信息。参数值:

  • true:展示;

  • false:不展示。

enable_citation boolean(可选)默认值为false

是否开启[1]或[ref_1]样式的角标标注功能。在enable_sourcetrue时生效。参数值:

  • true:开启;

  • false:不开启。

citation_format string(可选)默认值为[<number>]

角标样式。在enable_citationtrue时生效。参数值:

  • [<number>]:角标形式为[1]

  • [ref_<number>]:角标形式为[ref_1]

forced_search boolean(可选)默认值为false

是否强制开启搜索。参数值:

  • true:强制开启;

  • false:不强制开启。

search_strategy string(可选)默认值为standard

搜索互联网信息的数量。参数值:

  • standard:在请求时搜索5条互联网信息;

  • pro:在请求时搜索10条互联网信息。

chat响应对象(流式与非流式输出格式一致)

{
  "status_code": 200,
  "request_id": "902fee3b-f7f0-9a8c-96a1-6b4ea25af114",
  "code": "",
  "message": "",
  "output": {
    "text": null,
    "finish_reason": null,
    "choices": [
      {
        "finish_reason": "stop",
        "message": {
          "role": "assistant",
          "content": "我是阿里云开发的一款超大规模语言模型,我叫通义千问。"
        }
      }
    ]
  },
  "usage": {
    "input_tokens": 22,
    "output_tokens": 17,
    "total_tokens": 39
  }
}

status_code string

本次请求的状态码。200 表示请求成功,否则表示请求失败。

Java SDK不会返回该参数。调用失败会抛出异常,异常信息为status_codemessage的内容。

request_id string

本次调用的唯一标识符。

Java SDK返回参数为requestId。

code string

错误码,调用成功时为空值。

只有Python SDK返回该参数。

output object

调用结果信息。

属性

text string

模型生成的回复。当设置输入参数result_formattext时将回复内容返回到该字段。

finish_reason string

当设置输入参数result_formattext时该参数不为空。

有四种情况:

  • 正在生成时为null;

  • 因模型输出自然结束,或触发输入参数中的stop条件而结束时为stop;

  • 因生成长度过长而结束为length;

  • 因发生工具调用为tool_calls。

choices array

模型的输出信息。当result_formatmessage时返回choices参数。

属性

finish_reason string

有四种情况:

  • 正在生成时为null;

  • 因模型输出自然结束,或触发输入参数中的stop条件而结束时为stop;

  • 因生成长度过长而结束为length;

  • 因发生工具调用为tool_calls。

message object

模型输出的消息对象。

属性

role string

输出消息的角色,固定为assistant。

content string

输出消息的内容。

如果发起function call,则该值为空。

tool_calls array

如果模型需要调用工具,则会生成tool_calls参数。

属性

function object

调用工具的名称,以及输入参数。

属性

name string

调用工具的名称

arguments string

需要输入到工具中的参数,为JSON字符串。

由于大模型响应有一定随机性,输出的JSON字符串并不总满足于您的函数,建议您在将参数输入函数前进行参数的有效性校验。

index integer

当前tool_calls对象在tool_calls数组中的索引。

id string

本次工具响应的ID。

type string

工具类型,固定为function

search_info object

联网搜索到的信息,在设置search_options参数后会返回该参数。

属性

search_results array

联网搜索到的结果。

属性

site_name string

搜索结果来源的网站名称。

icon string

来源网站的图标URL,如果没有图标则为空字符串。

index integer

搜索结果的序号,表示该搜索结果在search_results中的索引。

title string

搜索结果的标题。

url string

搜索结果的链接地址。

usage map

本次chat请求使用的token信息。

属性

input_tokens integer

用户输入内容转换成token后的长度。

output_tokens integer

chat请求返回内容转换成token后的长度。

total_tokens integer

当输入为纯文本时返回该字段,为input_tokensoutput_tokens之和

image_tokens integer

输入内容包含image时返回该字段。为用户输入图片内容转换成token后的长度。

video_tokens integer

输入内容包含video时返回该字段。为用户输入视频内容转换成token后的长度。

audio_tokens integer

输入内容包含audio时返回该字段。为用户输入音频内容转换成token后的长度。

prompt_tokens_details object

输入 Token 的细粒度分类。

属性

cached_tokens integer

命中 Cache 的 Token 数。Context Cache 详情请参见Context Cache(上下文缓存)

错误码

如果模型调用失败并返回报错信息,请参见错误码进行解决。