Compatível com OpenAI - Chat - Alibaba Cloud Model Studio

Informações de compatibilidade

BASE_URL

A BASE_URL é o endpoint de rede para acessar o service de modelo. Ao usar a interface compatível com OpenAI no Model Studio, configure a BASE_URL conforme descrito abaixo. Para chamadas via OpenAI SDK ou outros SDKs compatíveis com OpenAI, utilize a seguinte BASE_URL:

Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Virginia: https://dashscope-us.aliyuncs.com/compatible-mode/v1
Beijing: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Hong Kong (China): https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Japan (Tokyo): https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1

Para chamadas via HTTP, use o endpoint completo abaixo:

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Virginia: POST https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions
Beijing: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Hong Kong (China): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Japan (Tokyo): POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions

O Model Studio introduziu nomes de domínio específicos por workspace para as regiões Beijing, Singapore e Hong Kong (China), oferecendo melhor desempenho e maior estabilidade. Migre para os novos nomes de domínio:

Região Beijing: Migre de https://dashscope.aliyuncs.com para https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Região Singapore: Migre de https://dashscope-intl.aliyuncs.com para https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Região Hong Kong (China): Migre de https://cn-hongkong.dashscope.aliyuncs.com para https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com

Substitua {WorkspaceId} pelo seu workspace ID real.

Solucionar falhas em chamadas : Se uma chamada pela interface compatível com OpenAI falhar com erro 404, 401, 403 ou de conexão, verifique as configurações a seguir:

Chamadas entre regiões

Uma chave de API do Model Studio está vinculada à região onde foi criada. Ao chamar a URL base de uma região, use obrigatoriamente uma chave de API criada nessa mesma região. O sistema rejeita chaves de API de outras regiões com um erro de autenticação. Essa regra se aplica a todas as regiões que fornecem um endpoint, incluindo China (Beijing), US (Virginia), Singapore e Japan (Tokyo), além de China (Hong Kong). Crie a chave de API no console da região cujo endpoint você pretende chamar. Por exemplo, ao usar uma chave de API criada na região China (Beijing) para chamar o endpoint US (Virginia), a solicitação retorna HTTP 401 com a mensagem de erro Incorrect API key provided e o código de erro invalid_api_key. Esse erro indica que a chave de API e o endpoint pertencem a regiões diferentes, e não que a chave é inválida ou carece de permissões.

Modelos suportados

Modelos suportados: grandes modelos de linguagem Qwen (edições comerciais e open-source), Qwen-VL, Qwen-Coder, Qwen-Omni, Qwen-Math, DeepSeek , Kimi , GLM , MiniMax .

O Qwen-Audio não oferece suporte ao protocolo compatível com OpenAI. Utilize o protocolo DashScope como alternativa.

Chamada via OpenAI SDK

Pré-requisitos

Python instalado em sua máquina.
Versão mais recente do OpenAI SDK instalada.

# If the following command fails, replace pip with pip3
pip install -U openai

Model Studio ativado e chave de API obtida. Para instruções, consulte Obter chave de API.
(Recomendado) Configure a chave de API como variável de ambiente para reduzir o risco de exposição. Também é possível configurá-la diretamente no código, mas isso aumenta o risco de exposição.
Selecione o modelo desejado na lista de modelos suportados.

Uso

Os exemplos a seguir demonstram como usar o OpenAI SDK para acessar modelos Qwen no Model Studio.

Exemplo sem streaming

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请用阿里云百炼API Key将本行替换为：api_key="sk-xxx"
        # 以下为新加坡地域base_url，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
    )
    completion = client.chat.completions.create(
        model="qwen3.8-max",  # 此处以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())

if __name__ == '__main__':
    get_response()

A saída retornada é:

{
    "id": "chatcmpl-xxx",
    "choices": [
        {
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null,
            "message": {
                "content": "我是来自阿里云的超大规模预训练模型，我叫千问。",
                "role": "assistant",
                "function_call": null,
                "tool_calls": null
            }
        }
    ],
    "created": 1716430652,
    "model": "qwen3.8-max",
    "object": "chat.completion",
    "system_fingerprint": null,
    "usage": {
        "completion_tokens": 18,
        "prompt_tokens": 22,
        "total_tokens": 40
    }
}

Exemplo com streaming

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        # 如果您没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        # 以下为新加坡地域base_url，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",

    )
    completion = client.chat.completions.create(
        model="qwen3.8-max",  # 此处以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': '你是谁？'}],
        stream=True,
        # 通过以下设置，在流式输出的最后一行展示token使用信息
        stream_options={"include_usage": True}
        )
    for chunk in completion:
        print(chunk.model_dump_json())

if __name__ == '__main__':
    get_response()

A saída retornada é:

{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"","function_call":null,"role":"assistant","tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"我是","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"来自","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"阿里","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"云的大规模语言模型","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"，我叫千问。","function_call":null,"role":null,"tool_calls":null},"finish_reason":null,"index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[{"delta":{"content":"","function_call":null,"role":null,"tool_calls":null},"finish_reason":"stop","index":0,"logprobs":null}],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":null}
{"id":"chatcmpl-xxx","choices":[],"created":1719286190,"model":"qwen3.8-max","object":"chat.completion.chunk","system_fingerprint":null,"usage":{"completion_tokens":16,"prompt_tokens":22,"total_tokens":38}}

Exemplo de chamada de ferramenta

O exemplo a seguir demonstra a chamada de ferramentas (function call) por meio da interface compatível com OpenAI, utilizando uma ferramenta de consulta meteorológica e outra de consulta de hora. O código suporta chamadas de ferramenta em múltiplas rodadas.

from openai import OpenAI
from datetime import datetime
import json
import os

client = OpenAI(
    # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # 若没有配置环境变量，请用阿里云百炼API Key将下行替换为：api_key="sk-xxx",
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    # 以下为新加坡地域base_url，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
    base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",
)

# 定义工具列表，模型在选择使用哪个工具时会参考工具的name和description
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"
            ]
        }
    }
]

# 模拟天气查询工具。返回结果示例："北京今天是雨天。"
def get_current_weather(location):
    return f"{location}今天是雨天。 "

# 查询当前时间的工具。返回结果示例："当前时间：2024-04-15 17:15:18。"
def get_current_time():
    # 获取当前日期和时间
    current_datetime = datetime.now()
    # 格式化当前日期和时间
    formatted_time = current_datetime.strftime('%Y-%m-%d %H:%M:%S')
    # 返回格式化后的当前时间
    return f"当前时间：{formatted_time}。"

# 封装模型响应函数
def get_response(messages):
    completion = client.chat.completions.create(
        model="qwen3.8-max",  # 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
        messages=messages,
        tools=tools
        )
    return completion.model_dump()

def call_with_messages():
    print('\n')
    messages = [
            {
                "content": input('请输入：'),  # 提问示例："现在几点了？" "一个小时后几点" "北京天气如何？"
                "role": "user"
            }
    ]
    print("-"*60)
    # 模型的第一轮调用
    i = 1
    first_response = get_response(messages)
    assistant_output = first_response['choices'][0]['message']
    print(f"\n第{i}轮大模型输出信息：{first_response}\n")
    if  assistant_output['content'] is None:
        assistant_output['content'] = ""
    messages.append(assistant_output)
    # 如果不需要调用工具，则直接返回最终答案
    if assistant_output['tool_calls'] == None:  # 如果模型判断无需调用工具，则将assistant的回复直接打印出来，无需进行模型的第二轮调用
        print(f"无需调用工具，我可以直接回复：{assistant_output['content']}")
        return
    # 如果需要调用工具，则进行模型的多轮调用，直到模型判断无需调用工具
    while assistant_output['tool_calls'] != None:
        # 如果判断需要调用查询天气工具，则运行查询天气工具
        if assistant_output['tool_calls'][0]['function']['name'] == 'get_current_weather':
            tool_info = {"name": "get_current_weather", "role":"tool"}
            # 提取位置参数信息
            location = json.loads(assistant_output['tool_calls'][0]['function']['arguments'])['location']
            tool_info['content'] = get_current_weather(location)
        # 如果判断需要调用查询时间工具，则运行查询时间工具
        elif assistant_output['tool_calls'][0]['function']['name'] == 'get_current_time':
            tool_info = {"name": "get_current_time", "role":"tool"}
            tool_info['content'] = get_current_time()
        print(f"工具输出信息：{tool_info['content']}\n")
        print("-"*60)
        messages.append(tool_info)
        assistant_output = get_response(messages)['choices'][0]['message']
        if  assistant_output['content'] is None:
            assistant_output['content'] = ""
        messages.append(assistant_output)
        i += 1
        print(f"第{i}轮大模型输出信息：{assistant_output}\n")
    print(f"最终答案：{assistant_output['content']}")

if __name__ == '__main__':
    call_with_messages()

Parâmetros de solicitação

Os parâmetros de solicitação estão alinhados com a interface OpenAI. A tabela a seguir descreve os parâmetros suportados atualmente:

Parâmetro	Tipo	Padrão	Descrição
model	string	-	Modelo a ser utilizado. Para modelos disponíveis, consulte Supported models.
messages	array	-	Histórico da conversa entre o usuário e o modelo. Cada elemento do array segue o formato `{"role": role, "content": content}`. Funções válidas: system, user, assistant. Apenas `messages[0]` aceita a função system. Em geral, as funções user e assistant se alternam, e o último elemento deve ter a função user.
top_p (opcional)	float	-	Limiar de probabilidade para amostragem nuclear. Por exemplo, um valor de 0,8 mantém apenas o menor conjunto de tokens cuja probabilidade acumulada seja de pelo menos 0,8. Valores válidos: (0, 1,0). Valores maiores aumentam a aleatoriedade; valores menores aumentam o determinismo.
temperature (opcional)	float	-	Controla a aleatoriedade e a diversidade das respostas do modelo. Valores maiores achatam a distribuição de probabilidade, selecionando mais tokens de baixa probabilidade para uma saída mais diversa. Valores menores tornam a distribuição mais aguda, favorecendo tokens de alta probabilidade para uma saída mais determinística. Valores válidos: [0, 2). Não recomendamos o uso do valor 0.
presence_penalty (opcional)	float	-	Controla a repetição em toda a sequência gerada. Valores maiores reduzem a repetição. Valores válidos: [-2,0, 2,0]. Suportado apenas em modelos comerciais Qwen e modelos open-source qwen1.5 e posteriores.
n (opcional)	integer	1	Número de respostas a serem geradas. Valores válidos: `1-4`. Para cenários que exigem múltiplas respostas (como escrita criativa ou textos publicitários), defina um valor maior para n. > Um valor maior de n não aumenta o consumo de tokens de entrada, mas eleva o consumo de tokens de saída. > Atualmente suportado apenas no qwen-plus. Quando o parâmetro `tools` é fornecido, n fica fixo em 1.
max_tokens (opcional)	integer	-	Número máximo de tokens que o modelo pode gerar. Por exemplo, se o modelo suporta até 2k tokens de saída, defina este valor como 1k para evitar respostas excessivamente longas. Diferentes modelos possuem limites distintos de saída. Consulte a lista de modelos para detalhes.
seed (opcional)	integer	-	Semente aleatória para geração, usada para controlar a aleatoriedade da saída do modelo. Aceita inteiros de 64 bits sem sinal.
stream (opcional)	boolean	False	Controla o uso de saída em streaming. Com o streaming ativado, a interface retorna um gerador. Itere sobre ele para obter resultados, onde cada saída corresponde à sequência incremental gerada.
stop (opcional)	string ou array	None	Controla a interrupção precisa da geração de conteúdo. A geração para automaticamente quando o modelo está prestes a produzir a string ou token_id especificado. Pode ser do tipo string ou array. Tipo string: a geração para quando o modelo está prestes a produzir a palavra de parada especificada. Tipo array: os elementos podem ser token_ids, strings ou arrays de token_ids. A geração para quando o token gerado ou seu token_id corresponder a um elemento em stop. Quando stop é do tipo array, não é possível misturar token_ids e strings como elementos.
tools (opcional)	array	None	Biblioteca de ferramentas disponível para chamada pelo modelo. Durante um fluxo de chamada de função, o modelo seleciona uma ferramenta desta biblioteca. Cada ferramenta possui a seguinte estrutura: `type` (string, atualmente apenas "function" é suportado), `function` (objeto com as chaves: `name`, `description`, `parameters`). O campo `name` é o nome da função (letras, números, sublinhados e hífens; máx. 64 caracteres). O campo `description` descreve quando e como o modelo deve chamar a função. O campo `parameters` é um JSON Schema válido que descreve os parâmetros da função. Se vazio, a função não recebe entrada. O campo `type` dentro de parameters suporta tipos comuns do JSON Schema: `string`, `number`, `integer`, `boolean`, `array` e `object`. Ao usar o tipo `array`, especifique os tipos dos elementos com `items`. Tanto a rodada de início da chamada de função quanto a rodada de envio do resultado da ferramenta requerem o parâmetro tools. Modelos suportados atualmente: qwen-turbo, qwen-plus e qwen-max. O parâmetro tools não pode ser usado simultaneamente com stream=True.
stream_options (opcional)	object	None	Configura a exibição do uso de tokens na saída em streaming. Só tem efeito quando stream é True. Para contar tokens no modo streaming, defina `stream_options={"include_usage": True}`.

Parâmetros de resposta

Parâmetro	Tipo	Descrição	Observações
id	string	ID gerado pelo sistema para esta solicitação.	-
model	string	Nome do modelo usado nesta solicitação.	-
system_fingerprint	string	Versão de configuração usada pelo runtime do modelo. Atualmente não suportado; retorna uma string vazia.	-
choices	array	Detalhes do conteúdo gerado pelo modelo.	-
choices[i].finish_reason	string	Motivo da interrupção da geração. Valores: null (ainda gerando), stop (parado devido a uma condição de parada), length (parado por exceder o comprimento máximo).	-
choices[i].message	object	Mensagem produzida pelo modelo.	-
choices[i].message.role	string	Função do modelo. Valor fixo: assistant.	-
choices[i].message.content	string	Texto gerado pelo modelo.	-
choices[i].index	integer	Número de sequência do resultado gerado. Padrão: 0.	-
created	integer	Timestamp (em segundos) do resultado gerado.	-
usage	object	Informações de medição indicando o consumo de tokens para esta solicitação.	-
usage.prompt_tokens	integer	Contagem de tokens do texto de entrada do usuário.	-
usage.completion_tokens	integer	Contagem de tokens da resposta gerada pelo modelo.	-
usage.total_tokens	integer	Soma de usage.prompt_tokens e usage.completion_tokens.	-

Chamada via langchain_openai SDK

Pré-requisitos

Python instalado em sua máquina.
langchain_openai SDK instalado.

# If the following command fails, replace pip with pip3
pip install -U langchain_openai

Model Studio ativado e chave de API obtida. Para instruções, consulte Obter chave de API.
(Recomendado) Configure a chave de API como variável de ambiente para reduzir o risco de exposição. Também é possível configurá-la diretamente no código, mas isso aumenta o risco de exposição.
Selecione o modelo desejado na lista de modelos suportados.

Uso

Os exemplos a seguir mostram como usar o langchain_openai SDK para acessar modelos Qwen no Model Studio.

Saída sem streaming

A saída sem streaming utiliza o método invoke:

from langchain_openai import ChatOpenAI
import os

def get_response():
    llm = ChatOpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请用阿里云百炼API Key将本行替换为：api_key="sk-xxx"
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1", # 以下为新加坡地域base_url，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
        model="qwen3.8-max"  # 此处以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":"你是谁？"}
    ]
    response = llm.invoke(messages)
    print(response.json())

if __name__ == "__main__":
    get_response()

A saída retornada é:

{
    "content": "我是来自阿里云的大规模语言模型，我叫千问。",
    "additional_kwargs": {},
    "response_metadata": {
        "token_usage": {
            "completion_tokens": 16,
            "prompt_tokens": 22,
            "total_tokens": 38
        },
        "model_name": "qwen-plus",
        "system_fingerprint": "",
        "finish_reason": "stop",
        "logprobs": null
    },
    "type": "ai",
    "name": null,
    "id": "run-xxx",
    "example": false,
    "tool_calls": [],
    "invalid_tool_calls": []
}

Saída com streaming

A saída com streaming utiliza o método stream. Não é necessário configurar um parâmetro stream separadamente.

from langchain_openai import ChatOpenAI
import os

def get_response():
    llm = ChatOpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        api_key=os.getenv("DASHSCOPE_API_KEY"),  # 如果您没有配置环境变量，请用阿里云百炼API Key将本行替换为：api_key="sk-xxx"
        base_url="https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1",   # 以下为新加坡地域base_url，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
        model="qwen3.8-max",   # 此处以qwen-plus为例，可按需更换模型名称。模型列表：https://www.alibabacloud.com/help/zh/model-studio/getting-started/models
        stream_usage=True
        )
    messages = [
        {"role":"system","content":"You are a helpful assistant."},
        {"role":"user","content":"你是谁？"},
    ]
    response = llm.stream(messages)
    for chunk in response:
        print(chunk.model_dump_json())

if __name__ == "__main__":
    get_response()

A saída retornada é:

{"content": "", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "我是", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "来自", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "阿里", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "云", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "的大规模语言模型", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "，我叫通", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "义千问。", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "", "additional_kwargs": {}, "response_metadata": {"finish_reason": "stop"}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": null, "tool_call_chunks": []}
{"content": "", "additional_kwargs": {}, "response_metadata": {}, "type": "AIMessageChunk", "name": null, "id": "run-xxx", "example": false, "tool_calls": [], "invalid_tool_calls": [], "usage_metadata": {"input_tokens": 22, "output_tokens": 16, "total_tokens": 38}, "tool_call_chunks": []}

Para detalhes sobre a configuração de parâmetros, consulte Request parameters. Os parâmetros são definidos no objeto ChatOpenAI.

Chamada via HTTP

Chame o Model Studio por meio de solicitações HTTP e receba respostas na mesma estrutura das respostas HTTP da OpenAI.

Pré-requisitos

Model Studio ativado e chave de API obtida. Para instruções, consulte Obter chave de API.
(Recomendado) Configure a chave de API como variável de ambiente para reduzir o risco de exposição. Também é possível configurá-la diretamente no código, mas isso aumenta o risco de exposição.

Endpoint

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Virginia: POST https://dashscope-us.aliyuncs.com/compatible-mode/v1/chat/completions
Beijing: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Hong Kong (China): POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/chat/completions

Exemplos de solicitação

Os exemplos abaixo utilizam comandos cURL para chamar a API.

Caso não tenha configurado sua chave de API como variável de ambiente, substitua $DASHSCOPE_API_KEY pela sua chave de API real.

Saída sem streaming

# 以下为新加坡地域URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.8-max",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "你是谁？"
        }
    ]
}'

A saída retornada é:

{
    "choices": [
        {
            "message": {
                "role": "assistant",
                "content": "我是来自阿里云的大规模语言模型，我叫千问。"
            },
            "finish_reason": "stop",
            "index": 0,
            "logprobs": null
        }
    ],
    "object": "chat.completion",
    "usage": {
        "prompt_tokens": 11,
        "completion_tokens": 16,
        "total_tokens": 27
    },
    "created": 1715252778,
    "system_fingerprint": "",
    "model": "qwen3.8-max",
    "id": "chatcmpl-xxx"
}

Saída com streaming

Para usar a saída com streaming, defina o parâmetro stream como true no corpo da solicitação.

# 以下为新加坡地域URL，调用时请将{WorkspaceId}替换为真实的业务空间ID，各地域URL不同。
curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY" \
--header 'Content-Type: application/json' \
--data '{
    "model": "qwen3.8-max",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "你是谁？"
        }
    ],
    "stream":true
}'

A saída retornada é:

data: {"choices":[{"delta":{"content":"","role":"assistant"},"index":0,"logprobs":null,"finish_reason":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"finish_reason":null,"delta":{"content":"我是"},"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"delta":{"content":"来自"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"delta":{"content":"阿里"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"delta":{"content":"云的大规模语言模型"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"delta":{"content":"，我叫千问。"},"finish_reason":null,"index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: {"choices":[{"delta":{"content":""},"finish_reason":"stop","index":0,"logprobs":null}],"object":"chat.completion.chunk","usage":null,"created":1715931028,"system_fingerprint":null,"model":"qwen3.8-max","id":"chatcmpl-3bb05cf5cd819fbca5f0b8d67a025022"}

data: [DONE]

Para detalhes dos parâmetros, consulte Request parameters.

Resposta de erro

Quando uma solicitação falha, a resposta inclui os campos code e message indicando a causa:

{
    "error": {
        "message": "Incorrect API key provided. ",
        "type": "invalid_request_error",
        "param": null,
        "code": "invalid_api_key"
    }
}

Configurar um cliente de terceiros

Chame modelos do Model Studio a partir de qualquer cliente de terceiros que suporte o protocolo compatível com OpenAI. Os passos abaixo usam o cliente Zhipu como exemplo:

Nas configurações de provedor do cliente, selecione Custom provider.
Base URL: Insira a URL base que o OpenAI SDK usa para sua região. Para a URL base de cada região, consulte BASE_URL. A URL base termina com /compatible-mode/v1 e não inclui /chat/completions. Como as URLs base variam por região, use aquela correspondente à região da sua chave de API. Por exemplo, para a região Singapore, insira https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Substitua {WorkspaceId} pelo ID do seu workspace, encontrado na página de detalhes do workspace no console do Model Studio. O domínio legado https://dashscope.aliyuncs.com permanece disponível, mas utilize o domínio específico do workspace sempre que possível.
API Key: Insira a chave de API do Model Studio referente à região apontada pela URL base. Crie e obtenha uma chave de API na página de gerenciamento de API Key do console do Model Studio.
Model name: Insira o nome de um grande modelo de linguagem que suporte o protocolo compatível com OpenAI. Para os modelos disponíveis, consulte Supported models. Por exemplo, qwen3-vl-32b-thinking. Este nome de modelo é apenas um exemplo e não indica que o modelo oferece cota gratuita.
Salve a configuração e inicie uma conversa para verificar se o cliente de terceiros consegue chamar o modelo.

Uma chamada pode retornar HTTP 400 com error.message definido como current user api does not support http call e error.type definido como invalid_request_error. Esse erro significa que o modelo inserido não suporta chamadas HTTP pela interface compatível com OpenAI. Substitua-o por um modelo listado em Supported models e tente novamente. Por exemplo, qvq-max não suporta este método de chamada.

Códigos de erro

Código de erro	Descrição
400 - Invalid Request Error	A solicitação é inválida. Consulte a mensagem de erro para detalhes.
401 - Incorrect API key provided	A chave de API está incorreta.
429 - Rate limit reached for requests	Limite de QPS ou QPM excedido.
429 - You exceeded your current quota, please check your plan and billing details	Cota excedida ou conta inadimplente.
500 - The server had an error while processing your request	Erro no servidor.
503 - The engine is currently overloaded, please try again later	Servidor sobrecarregado. Tente novamente mais tarde.

​Informações de compatibilidade

​BASE_URL

​Chamadas entre regiões

​Modelos suportados

​Chamada via OpenAI SDK

​Pré-requisitos

​Uso

​Exemplo sem streaming

​Exemplo com streaming

​Exemplo de chamada de ferramenta

​Parâmetros de solicitação

​Parâmetros de resposta

​Chamada via langchain_openai SDK

​Pré-requisitos

​Uso

​Saída sem streaming

​Saída com streaming

​Chamada via HTTP

​Pré-requisitos

​Endpoint

​Exemplos de solicitação

​Saída sem streaming

​Saída com streaming

​Resposta de erro

​Configurar um cliente de terceiros

​Códigos de erro

Informações de compatibilidade

BASE_URL

Chamadas entre regiões

Modelos suportados

Chamada via OpenAI SDK

Pré-requisitos

Uso

Exemplo sem streaming

Exemplo com streaming

Exemplo de chamada de ferramenta

Parâmetros de solicitação

Parâmetros de resposta

Chamada via langchain_openai SDK

Pré-requisitos

Uso

Saída sem streaming

Saída com streaming

Chamada via HTTP

Pré-requisitos

Endpoint

Exemplos de solicitação

Saída sem streaming

Saída com streaming

Resposta de erro

Configurar um cliente de terceiros

Códigos de erro