Llame a los modelos Qwen mediante la API_Alibaba Cloud Model Studio(Model Studio) - Alibaba Cloud Model Studio

Los modelos Qwen en Model Studio admiten interfaces compatibles con OpenAI. Puede migrar su código existente de OpenAI a Model Studio cambiando únicamente la clave de API, la URL base y el nombre del modelo.

Información de compatibilidad

BASE_URL

El BASE_URL es el endpoint de red para acceder al servicio de modelos. Cuando utilice la interfaz compatible con OpenAI con Model Studio, configure el BASE_URL de la siguiente manera.

Cuando realiza la llamada mediante el SDK de OpenAI u otros SDK compatibles con OpenAI, utilice el siguiente BASE_URL:

Singapore: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Virginia: https://{WorkspaceId}.us-east-1.maas.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

Cuando realiza la llamada mediante HTTP, utilice el siguiente endpoint completo:

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Virginia: POST https://{WorkspaceId}.us-east-1.maas.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

ImportanteModel Studio ha introducido nombres de dominio específicos del espacio de trabajo para las regiones de Beijing, Singapur y Hong Kong (China) que ofrecen un mejor rendimiento y mayor estabilidad. Migre a los nuevos nombres de dominio:

Región de Beijing: Migrar de https://dashscope.aliyuncs.com a https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
Región de Singapur: Migrar de https://dashscope-intl.aliyuncs.com a https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Región de Hong Kong (China): Migrar de https://cn-hongkong.dashscope.aliyuncs.com a https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com

Reemplace {WorkspaceId} con su ID de espacio de trabajo real.

Solución de problemas de llamadas fallidas: Si una llamada a través de la interfaz compatible con OpenAI falla con un error 404, 401, 403 o de conexión, verifique las siguientes configuraciones:

Llamadas entre regiones

Una clave de API de Model Studio está vinculada a la región en la que se creó. Cuando llame a la URL base de una región, debe utilizar una clave de API que se haya creado en esa misma región. Una clave de API de otra región se rechazará con un error de autenticación.

Esta regla se aplica a cada región que proporciona un endpoint, incluidas China (Beijing), EE. UU. (Virginia), Singapore y Japan (Tokyo), así como China (Hong Kong). Cree la clave de API en la consola de la región cuyo endpoint va a llamar.

Por ejemplo, si utiliza una clave de API creada en la región de China (Beijing) para llamar al endpoint de EE. UU. (Virginia), la solicitud devolverá HTTP 401 con el mensaje de error Incorrect API key provided y el código de error invalid_api_key. Este error indica que la clave de API y el endpoint pertenecen a diferentes regiones, no que la clave de API sea inválida o carezca de permisos.

Modelos admitidos

Modelos compatibles: modelos de lenguaje grande Qwen (ediciones comerciales y de código abierto), Qwen-VL, Qwen-Coder, Qwen-Omni, Qwen-Math, DeepSeek, Kimi, GLM, MiniMax.

Qwen-Audio no admite el protocolo compatible con OpenAI. Utilice el protocolo DashScope en su lugar.

Llamada mediante el SDK de OpenAI

Requisitos previos

Python está instalado en su equipo.
La última versión del SDK de OpenAI está instalada.

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

Ha activado Model Studio y ha obtenido una clave de API. Para obtener instrucciones, consulte Obtener clave de API.
(Recomendado) Configure la clave de API como variable de entorno para reducir el riesgo de exposición de la clave. También puede configurarla directamente en el código, pero esto aumenta el riesgo de exposición.
Seleccione el modelo que want utilizar de la lista de modelos compatibles.

Uso

Los siguientes ejemplos muestran cómo utilizar el SDK de OpenAI para acceder a los modelos Qwen en Model Studio.

Ejemplo sin streaming

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/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/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()

Se devuelve la siguiente salida:

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

Ejemplo de streaming

from openai import OpenAI
import os

def get_response():
    client = OpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/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/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()

Se devuelve la siguiente salida:

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

Ejemplo de llamada de herramientas

El siguiente ejemplo demuestra la llamada de herramientas (llamada de función) a través de la interfaz compatible con OpenAI, utilizando una herramienta de consulta meteorológica y una herramienta de consulta horaria. El código de ejemplo admite llamadas de herramientas de múltiples turnos.

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

client = OpenAI(
    # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/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/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 solicitud

Los parámetros de solicitud están alineados con la interfaz de OpenAI. La siguiente tabla describe los parámetros admitidos actualmente:

Parámetro	Tipo	Predeterminado	Descripción
model	string	-	El modelo a utilizar. Para ver los modelos disponibles, consulte Modelos compatibles.
messages	array	-	El historial de conversaciones entre el usuario y el modelo. Cada elemento del arreglo tiene el formato `{"role": role, "content": content}`. Roles válidos: system, user, assistant. Solo `messages[0]` admite el rol system. En general, los roles user y assistant se alternan, y el último elemento debe tener el rol user.
top_p (optional)	float	-	El umbral de probabilidad de muestreo de núcleo. Por ejemplo, un valor de 0.8 conserva solo el conjunto más pequeño de tokens cuya probabilidad acumulada es al menos 0.8. Valores válidos: (0, 1.0). Los valores más altos aumentan la aleatoriedad; los valores más bajos aumentan el determinismo.
temperature (optional)	float	-	Controla la aleatoriedad y diversidad de las respuestas del modelo. Los valores más altos aplanan la distribución de probabilidad, seleccionando más tokens de baja probabilidad para una salida más diversa. Los valores más bajos agudizan la distribución, favoreciendo tokens de alta probabilidad para una salida más determinista. Valores válidos: [0, 2). No se recomienda un valor de 0.
presence_penalty (optional)	float	-	Controla la repetición en toda la secuencia generada. Los valores más altos reducen la repetición. Valores válidos: [-2.0, 2.0]. Compatible solo con modelos comerciales Qwen y modelos de código abierto qwen1.5 y posteriores.
n (optional)	integer	1	El número de respuestas a generar. Valores válidos: `1-4`. Para escenarios que requieren múltiples respuestas (como escritura creativa o textos publicitarios), establezca un valor n mayor. > Un valor n mayor no aumenta el consumo de tokens de entrada, pero sí incrementa el consumo de tokens de salida. > Actualmente compatible solo con qwen-plus. Cuando se proporciona el parámetro `tools`, n se fija en 1.
max_tokens (optional)	integer	-	El número máximo de tokens que el modelo puede generar. Por ejemplo, si el modelo admite hasta 2k tokens de salida, puede establecer esto en 1k para evitar respuestas excesivamente largas. Diferentes modelos tienen distintos límites de salida. Consulte la lista de modelos para obtener más detalles.
seed (optional)	integer	-	La semilla aleatoria para la generación, utilizada para controlar la aleatoriedad de la salida del modelo. Admite enteros sin signo de 64 bits.
stream (optional)	boolean	False	Controla si se debe utilizar la salida en streaming. Cuando el streaming está habilitado, la interfaz devuelve un generador. Itere sobre él para obtener resultados, donde cada salida es la secuencia incremental generada.
stop (optional)	cadena o arreglo	None	Controla la detención precisa de la generación de contenido. La generación se detiene automáticamente cuando el modelo está a punto de producir la cadena especificada o token_id. Puede ser de tipo cadena o matriz. Cuando es de tipo cadena: la generación se detiene cuando el modelo está a punto de producir la palabra de parada especificada. Cuando es de tipo matriz: los elementos de la matriz pueden ser token_ids, cadenas o matrices de token_ids. La generación se detiene cuando el token generado o su token_id coincide con un elemento en stop. Cuando stop es de tipo arreglo, no puede mezclar token_ids y cadenas como elementos.
tools (optional)	array	None	La biblioteca de herramientas disponible para que el modelo las invoque. Durante un flujo de llamada de función, el modelo selecciona una herramienta de esta biblioteca. Cada herramienta tiene la siguiente estructura: `type` (cadena, actualmente solo se admite "function"), `function` (objeto con claves: `name`, `description`, `parameters`). El campo `name` es el nombre de la función (letras, números, guiones bajos y guiones; máximo 64 caracteres). El campo `description` describe cuándo y cómo debe el modelo llamar a la función. El campo `parameters` es un esquema JSON válido que describe los parámetros de la función. Si está vacío, la función no recibe entradas. El campo `type` dentro de parameters admite tipos comunes de esquema JSON: `string`, `number`, `integer`, `boolean`, `array` y `object`. Al usar el tipo `array`, especifique los tipos de elementos con `items`. Tanto el turno de inicio de la llamada de función como el turno de envío del resultado de la herramienta requieren el parámetro tools. Modelos admitidos actualmente: qwen-plus y qwen-max. El parámetro tools no se puede utilizar simultáneamente con stream=True.
stream_options (optional)	object	None	Configura si se debe mostrar el uso de tokens en la salida en streaming. Solo surte efecto cuando stream es True. Para contar tokens en modo streaming, establezca `stream_options={"include_usage": True}`.

Parámetros de respuesta

Parámetro	Tipo	Descripción	Notas
id	string	El ID generado por el sistema para esta solicitud.	-
model	string	El nombre del modelo utilizado para esta solicitud.	-
system_fingerprint	string	La versión de configuración utilizada por el entorno de ejecución del modelo. Actualmente no es compatible; devuelve una cadena vacía.	-
choices	array	Los detalles del contenido generado por el modelo.	-
choices[i].finish_reason	string	El motivo por el que se detuvo la generación. Valores: null (sigue generando), stop (detenido debido a una condición de parada), length (detenido por superar la longitud máxima).	-
choices[i].message	object	El mensaje generado por el modelo.	-
choices[i].message.role	string	El rol del modelo. Valor fijo: assistant.	-
choices[i].message.content	string	El texto generado por el modelo.	-
choices[i].index	integer	El número de secuencia del resultado generado. Predeterminado: 0.	-
created	integer	La marca de tiempo (en segundos) del resultado generado.	-
usage	object	Información de medición que indica el consumo de tokens para esta solicitud.	-
usage.prompt_tokens	integer	El recuento de tokens del texto de entrada del usuario.	-
usage.completion_tokens	integer	El recuento de tokens de la respuesta generada por el modelo.	-
usage.total_tokens	integer	La suma de usage.prompt_tokens y usage.completion_tokens.	-

Llamada mediante el SDK langchain_openai

Requisitos previos

Python está instalado en su equipo.
El SDK langchain_openai está instalado.

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

Ha activado Model Studio y ha obtenido una clave de API. Para obtener instrucciones, consulte Obtener clave de API.
(Recomendado) Configure la clave de API como variable de entorno para reducir el riesgo de exposición de la clave. También puede configurarla directamente en el código, pero esto aumenta el riesgo de exposición.
Seleccione el modelo que want utilizar de la lista de modelos compatibles.

Uso

Los siguientes ejemplos muestran cómo utilizar el SDK langchain_openai para acceder a los modelos Qwen en Model Studio.

Salida sin streaming

La salida sin streaming utiliza el método invoke:

from langchain_openai import ChatOpenAI
import os

def get_response():
    llm = ChatOpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/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/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()

Se devuelve la siguiente salida:

{
    "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": []
}

Salida por secuencias

La salida en streaming utiliza el método stream. No necesita configurar un parámetro de stream por separado.

from langchain_openai import ChatOpenAI
import os

def get_response():
    llm = ChatOpenAI(
        # 各地域的API Key不同。获取API Key：https://www.alibabacloud.com/help/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/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()

Se devuelve la siguiente salida:

{"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 obtener detalles sobre la configuración de parámetros, consulte Parámetros de solicitud. Los parámetros se definen en el objeto ChatOpenAI.

Llamada mediante HTTP

Puede llamar a Model Studio mediante solicitudes HTTP y recibir respuestas con la misma estructura que las respuestas HTTP de OpenAI.

Requisitos previos

Ha activado Model Studio y ha obtenido una clave de API. Para obtener instrucciones, consulte Obtener clave de API.
(Recomendado) Configure la clave de API como variable de entorno para reducir el riesgo de exposición de la clave. También puede configurarla directamente en el código, pero esto aumenta el riesgo de exposición.

Endpoint

Singapore: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/chat/completions
Virginia: POST https://{WorkspaceId}.us-east-1.maas.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

Ejemplos de solicitud

Los siguientes ejemplos utilizan comandos cURL para llamar a la API.

NotaSi no ha configurado su clave de API como variable de entorno, reemplace $DASHSCOPE_API_KEY con su clave de API real.

Salida sin 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": "你是谁？"
        }
    ]
}'

Se devuelve la siguiente salida:

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

Salida por secuencias

Para utilizar la salida en streaming, establezca el parámetro stream en true en el cuerpo de la solicitud.

# 以下为新加坡地域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
}'

Se devuelve la siguiente salida:

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 obtener detalles sobre los parámetros, consulte Parámetros de solicitud.

Respuesta de error

Cuando una solicitud falla, la respuesta incluye los campos code y message que indican la causa:

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

Configurar un cliente de terceros

Puede llamar a los modelos de Model Studio desde cualquier cliente de terceros que admita el protocolo compatible con OpenAI. Los siguientes pasos utilizan el cliente Zhipu como ejemplo:

En la configuración del proveedor del cliente, seleccione Custom provider.
Base URL: Introduzca la URL base que el SDK de OpenAI utiliza para su región. Para consultar la URL base de cada región, véase BASE_URL. La URL base termina con /compatible-mode/v1 y no incluye /chat/completions. Dado que las URL base difieren según la región, utilice la correspondiente a la región de su clave de API.

Por ejemplo, para la región de Singapore, introduzca https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1. Reemplace {WorkspaceId} con su ID de espacio de trabajo, que puede encontrar en la página de detalles del espacio de trabajo en la consola de Model Studio. El dominio heredado https://dashscope.aliyuncs.com sigue disponible, pero utilice el dominio específico del espacio de trabajo siempre que sea posible.
API Key: Introduzca la clave de API de Model Studio correspondiente a la región a la que apunta la URL base. Puede crear y obtener una clave de API en la página de API Key management de la consola de Model Studio.
Nombre del modelo: Introduzca el nombre de un modelo de lenguaje grande que admita el protocolo compatible con OpenAI. Para ver los modelos entre los que puede elegir, consulte Modelos compatibles. Por ejemplo, qwen3.7-plus. Este nombre de modelo es solo un ejemplo y no indica que el modelo proporcione una cuota gratuita.
Guarde la configuración e inicie una conversación para verificar que el cliente de terceros puede llamar al modelo.

Una llamada puede devolver HTTP 400 con error.message establecido en current user api does not support http call y error.type establecido en invalid_request_error. Este error significa que el modelo que introdujo no admite llamadas HTTP a través de la interfaz compatible con OpenAI. Reemplácelo con un modelo de Modelos compatibles e inténtelo de nuevo.

Códigos de error

Código de error	Descripción
400 - Error de solicitud no válida	La solicitud no es válida. Consulte el mensaje de error para obtener más detalles.
401 - Clave de API proporcionada incorrecta	La clave de API es incorrecta.
429 - Límite de tasa alcanzado para solicitudes	Se ha excedido el límite de QPS o QPM.
429 - Ha excedido su cuota actual; revise su plan y los detalles de facturación	Cuota excedida o cuenta con saldo pendiente.
500 - El servidor tuvo un error al procesar su solicitud	Error del servidor.
503 - El motor está actualmente sobrecargado, inténtelo de nuevo más tarde	Servidor sobrecargado. Inténtelo de nuevo más tarde.