全部產品
Search
文件中心

Alibaba Cloud Model Studio:通義千問API參考

更新時間:Dec 25, 2024

本文介紹通義千問API的輸入輸出參數。

模型介紹、選型建議和使用方法請參考文本產生。也可以查看通義千問VL模型的用法:視覺理解

您可以通過OpenAI 相容或DashScope的方式調用通義千問API。

OpenAI 相容

公用雲端

使用SDK調用時需配置的base_url:https://dashscope-intl.aliyuncs.com/compatible-mode/v1

使用HTTP方式調用時需配置的endpoint:POST https://dashscope-intl.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-intl.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
    model="qwen-plus", # 模型列表:https://www.alibabacloud.com/help/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-intl.aliyuncs.com/compatible-mode/v1"
    }
);

async function main() {
    const completion = await openai.chat.completions.create({
        model: "qwen-plus",  //模型列表:https://www.alibabacloud.com/help/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-intl.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-intl.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://www.alibabacloud.com/help/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-intl.com/compatible-mode/v1/chat/completions";
        // 模型列表:https://www.alibabacloud.com/help/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://www.alibabacloud.com/help/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-intl.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-intl.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-intl.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-intl.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-intl.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-intl.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-intl.aliyuncs.com/compatible-mode/v1"
    }
);

async function main() {
    const response = await openai.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"}}
        ]}]
    });
    console.log(JSON.stringify(response));
}

main();

curl

curl -X POST https://dashscope-intl.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"}}]
    }]
}'

工具調用

完整的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-intl.aliyuncs.com/compatible-mode/v1",  # 填寫DashScope SDK的base_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-intl.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-intl.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"]
            }
        }
    }
  ]
}'

非同步呼叫

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-intl.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())

model string (必選)

模型名稱。

支援的模型:通義千問大語言模型(商業版、開源版)、通義千問VL

具體模型名稱和計費,請參見模型列表

messages array (必選)

由歷史對話組成的訊息列表。

訊息類型

System Message object (可選)

模型的目標或角色。如果設定系統訊息,請放在messages列表的第一位。

屬性

content string (必選)

訊息內容。

role string (必選)

固定為system

User Message object (必選)

使用者發送給模型的訊息。

屬性

content string 或 array (必選)

訊息內容。如果您的輸入只有文本,則為string類型;如果您的輸入包含映像等多模態資料,則為array類型。

屬性

type string (必選)

有三個可取值:textimage_url

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"}。

role string (必選)

固定為user

Assistant Message object (可選)

模型對使用者訊息的回複。

屬性

content string (可選)

訊息內容。僅當助手訊息中指定tool_calls參數時非必選。

role string (必選)

固定為assistant

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(預設值):模型產生完所有內容後一次性返回結果。

  • true:邊產生邊輸出,即每產生一部分內容就立即輸出一個片段(chunk)。您需要即時地逐個讀取這些片段以獲得完整的結果。

stream_options object (可選)

當啟用流式輸出時,可通過將本參數設定為{"include_usage": true},在輸出的最後一行顯示所使用的Token數。

如果設定為false,則最後一行不顯示使用的Token數。

本參數僅在設定stream為true下生效。

temperature float (可選)

採樣溫度,控制模型產生文本的多樣性。

temperature越高,產生的文本更多樣,反之,產生的文本更確定。

取值範圍: [0, 2)

由於temperature與top_p均可以控制產生文本的多樣性,因此建議您只設定其中一個值。更多說明,請參見Temperature 和 top_p

top_p float (可選)

核採樣的機率閾值,控制模型產生文本的多樣性。

top_p越高,產生的文本更多樣。反之,產生的文本更確定。

取值範圍:(0,1.0]

由於temperature與top_p均可以控制產生文本的多樣性,因此建議您只設定其中一個值。更多說明,請參見Temperature 和 top_p

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:這部電影很好。情節很好,演技很好,音樂也很好,總的來說,整部電影都很好。實際上,它真的很棒。情節非常好,演技也非常好,音樂也非常好。

max_tokens integer (可選)

本次請求返回的最大 Token 數。

max_tokens 的設定不會影響大模型的產生過程,如果模型產生的 Token 數超過max_tokens,本次請求會返回截斷後的內容。

預設值和最大值都是模型的最大輸出長度。關於各模型的最大輸出長度,請參見模型列表

max_tokens參數適用於需要限制字數(如產生摘要、關鍵詞)、控製成本或減少回應時間的情境。

seed integer (可選)

設定seed參數會使文本產生過程更具有確定性,通常用於使模型每次啟動並執行結果一致。

在每次模型調用時傳入相同的seed值(由您指定),並保持其他參數不變,模型將儘可能返回相同的結果。

取值範圍:無符號64位整數,即0到264−1。

stop string 或 array (可選)

使用stop參數後,當模型產生的文本即將包含指定的字串或token_id時,將自動停止產生。

您可以在stop參數中傳入敏感詞來控制模型的輸出。

stop為array類型時,不可以將token_id和字串同時作為元素輸入,比如不可以指定stop為["你好",104307]

tools array (可選)

可供模型調用的工具數組,可以包含一個或多個工具對象。一次function call流程模型會從中選擇一個工具。

目前不支援通義千問VL。

屬性

type string (必選)

tools的類型,當前僅支援function。

function object (必選)

屬性

name string (必選)

工具函數的名稱,必須是字母、數字,可以包含底線和短劃線,最大長度為64。

description string (必選)

工具函數的描述,供模型選擇何時以及如何調用工具函數。

parameters object (必選)

工具的參數描述,需要是一個合法的JSON Schema。JSON Schema的描述可以見連結。如果parameters參數為空白,表示function沒有入參。

chat響應對象(非流式輸出)

{
  "id": "chatcmpl-0da38de9-5d2b-916d-9c6a-7af95993e275",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": null,
      "message": {
        "content": "我是通義千問,由阿里雲開發的AI助手。我被設計用來回答各種問題、提供資訊和與使用者進行對話。有什麼我可以協助你的嗎?",
        "role": "assistant",
        "function_call": null,
        "tool_calls": null
      }
    }
  ],
  "created": 1721044114,
  "model": "qwen-plus",
  "object": "chat.completion",
  "service_tier": null,
  "system_fingerprint": null,
  "usage": {
    "completion_tokens": 36,
    "prompt_tokens": 22,
    "total_tokens": 58
  }
}

id string

本次調用的唯一識別碼。

choices array

模型產生內容的數組,可以包含一個或多個choices對象。

屬性

finish_reason string

有三種情況:

  • 因觸發輸入參數中的stop條件,或自然停止輸出時為stop

  • 因產生長度過長而結束為length

  • 因需要調用工具而結束為tool_calls

index integer

choices列表中的序列編號。

logprobs object

該參數當前固定為null

message object

本次調用模型輸出的訊息。

屬性

content string

本次調用模型產生的文本。

role string

訊息的角色,固定為assistant

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的總和。

chat響應chunk對象(流式輸出)

{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"我是","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"阿里","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"雲","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"開發的一款超大規模語言","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"模型,我叫通義千問","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"。","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[{"delta":{"content":"","function_call":null,"refusal":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1724916712,"model":"qwen-turbo","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":null}
{"id":"chatcmpl-ecd76cbd-ec86-9546-880f-556fd2bb44b5","choices":[],"created":1724916712,"model":"qwen-plus","object":"chat.completion.chunk","service_tier":null,"system_fingerprint":null,"usage":{"completion_tokens":17,"prompt_tokens":22,"total_tokens":39}}

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

需要輸入到工具中的參數,所有chunk的arguments拼接後為完整的JSON字串。

由於大模型響應有一定隨機性,輸出的JSON字串並不總滿足於您的函數,建議您在將參數輸入函數前進行參數的有效性校正。

name string

函數名稱,只在第一個chunk中有值。

type string

工具的類型,當前只支援function

finish_reason string

有四種情況:

  • 因觸發輸入參數中的stop條件,或自然停止輸出時為stop

  • 當產生未結束時為null

  • 因產生長度過長而結束為length

  • 因需要調用工具而結束為tool_calls

index integer

choices列表中的序列編號。

created integer

本次chat請求被建立時的時間戳記。每個chunk對象有相同的時間戳記。

model string

本次chat請求使用的模型名稱。

object string

始終為chat.completion.chunk

usage object

本次chat請求使用的Token資訊。只在include_usagetrue時,在最後一個chunk顯示。

屬性

prompt_tokens integer

使用者的輸入轉換成Token後的長度。

completion_tokens integer

模型產生回複轉換為Token後的長度。

total_tokens integer

prompt_tokenscompletion_tokens的總和。

DashScope

公用雲端

  • 通過HTTP調用時需配置的endpoint:

    使用通義千問大語言模型:POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/text-generation/generation

    使用通義千問VL模型:POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation

  • 通過SDK調用時需配置的base_url:

    • Python代碼:

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

    • Java代碼:

      • 方式一:

        import com.alibaba.dashscope.protocol.Protocol;
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
      • 方式二:

        import com.alibaba.dashscope.utils.Constants;
        Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
您需要已擷取API Key配置API Key到環境變數。如果通過DashScope SDK進行調用,還需要安裝DashScope SDK

請求體

文本輸入

Python

import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
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://www.alibabacloud.com/help/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;
import com.alibaba.dashscope.protocol.Protocol;

public class Main {
    public static GenerationResult callWithMessage() throws ApiException, NoApiKeyException, InputRequiredException {
        Generation gen = new Generation(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        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

PHP

<?php

$url = "https://dashscope-intl.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-intl.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);
});

流式輸出

Python

import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
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;
import com.alibaba.dashscope.protocol.Protocol;

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(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
            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-intl.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

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
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;
import com.alibaba.dashscope.utils.Constants;
public class Main {
    static {
     Constants.baseHttpApiUrl="https://dashscope-intl.aliyuncs.com/api/v1";
    }
    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-intl.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": "這些是什麼?"}
                ]
            }
        ]
    }
}'

工具調用

完整的Function Call流程代碼請參考:Function Call(工具調用)

Python

import os
import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
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;
import com.alibaba.dashscope.protocol.Protocol;

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(Protocol.HTTP.getValue(), "https://dashscope-intl.aliyuncs.com/api/v1");
        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-intl.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
import dashscope
from dashscope.aigc.generation import AioGeneration

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
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())

model string (必選)

模型名稱。

支援的模型:通義千問大語言模型(商業版、開源版)、通義千問VL

具體模型名稱和計費,請參見模型列表

messages array (必選)

由歷史對話組成的訊息列表。

通過HTTP調用時,請將messages 放入 input 對象中。

訊息類型

System Message object

模型的目標或角色。如果設定系統訊息,請放在messages列表的第一位。

屬性

content string (必選)

訊息內容。

role string (必選)

固定為system

User Message object

使用者發送給模型的訊息。

屬性

content string 或 array (必選)

使用者訊息的內容。使用qwen 大語言模型時為string,使用qwen-vl系列模型時為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"]}

如果您需要直接輸入視頻檔案,請提交工單進行申請以及擷取使用方式。

role string (必選)

使用者訊息的角色,固定為user

Assistant Message object

模型對使用者訊息的回複。

屬性

content string (必選)

助手訊息的內容。

role string (必選)

助手訊息的角色,固定為assistant

Tool Message object

工具的輸出資訊。詳細說明:Function Call(工具調用)

屬性

content string (必選)

工具訊息的內容,一般為工具函數的輸出。

role string (必選)

工具訊息的角色,固定為tool

temperature float (可選)

採樣溫度,控制模型產生文本的多樣性。

temperature越高,產生的文本更多樣,反之,產生的文本更確定。

取值範圍: [0, 2)

通過HTTP調用時,請將 temperature 放入 parameters 對象中。

top_p float (可選)

核採樣的機率閾值,控制模型產生文本的多樣性。

top_p越高,產生的文本更多樣。反之,產生的文本更確定。

取值範圍:(0,1.0]。

Java SDK中為topP通過HTTP調用時,請將 top_p 放入 parameters 對象中。

top_k integer (可選)

產生過程中採樣候選集的大小。例如,取值為50時,僅將單次產生中得分最高的50個Token組成隨機採樣的候選集。取值越大,產生的隨機性越高;取值越小,產生的確定性越高。取值為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 對象中。

vl_high_resolution_images boolean (可選)預設值為 false

是否提高輸入圖片的預設Token上限,只適用於qwen-vl-max模型。輸入圖片的預設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位整數,即0到264−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參數中傳入敏感詞來控制模型的輸出。

stop為array類型時,不可以將token_id和字串同時作為元素輸入,比如不可以指定stop為["你好",104307]

tools array (可選)

可供模型調用的工具數組,可以包含一個或多個工具對象。一次function call流程模型會從中選擇其中一個工具。使用tools時需要同時指定result_format參數為message。在function call流程中,無論是發起function call,還是向模型提交工具函數的執行結果,均需設定tools參數。

目前不支援通義千問VL。

屬性

type string (必選)

tools的類型,當前僅支援function。

function object (必選)

屬性

name string (必選)

工具函數的名稱,必須是字母、數字,可以包含底線和短劃線,最大長度為64。

description string (必選)

工具函數的描述,供模型選擇何時以及如何調用工具函數。

parameters objcet (必選)

工具的參數描述,需要是一個合法的JSON Schema。JSON Schema的描述可以見連結。如果parameters參數為空白,表示function沒有入參。

通過HTTP調用時,請將 tools 放入 parameters JSON 對象中。暫時不支援qwen-vl系列模型。

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 對象中。

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_format為message時返回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

usage object

本次chat請求使用的token資訊。

屬性

input_tokens integer

使用者輸入內容轉換成token後的長度。

output_tokens integer

chat請求返回內容轉換成token後的長度。

total_tokens integer

當輸入為純文字時返回該欄位,為input_tokensoutput_tokens之和

image_tokens integer

輸入內容包含image時返回該欄位。為使用者輸入圖片內容轉換成token後的長度。

audio_tokens integer

輸入內容包含audio時返回該欄位。為使用者輸入音頻內容轉換成token後的長度。

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。