Utilice la API de Responses compatible con OpenAI para llamar al modelo Qwen. Este tema describe los parámetros de entrada y salida, y proporciona un ejemplo de llamada.
Ventajas sobre la API de Chat Completions de OpenAI:- Herramientas integradas: Obtenga mejores resultados en tareas complejas con herramientas integradas como búsqueda web, extracción web, intérprete de código, texto a imagen, imagen a imagen y búsqueda en base de conocimientos. Para obtener más información, consulte llamada a herramientas.
- Entrada más flexible: Admite tanto la entrada directa de cadenas como matrices de mensajes en formato de chat.
- Gestión simplificada del contexto: Evite construir manualmente una matriz de historial de mensajes pasando el
previous_response_idde la última respuesta. - Almacenamiento en caché de contexto conveniente: Agregue
x-dashscope-session-cache: enable(valor predeterminado: disable) al encabezado de la solicitud para habilitar el almacenamiento en caché automático del contexto de conversación en el servidor. Esto reduce la latencia de inferencia y los costos para conversaciones de múltiples turnos sin necesidad de cambios en el código. Para más detalles, consulte caché de sesión.
Compatibilidad y limitaciones
Esta API es compatible con OpenAI para reducir el costo de migración de los desarrolladores, pero difiere en sus parámetros, funcionalidad y comportamiento.
Principio fundamental: Solo se procesan los parámetros explícitamente listados en este documento. Cualquier parámetro de OpenAI no mencionado se ignora.
Las siguientes diferencias clave le ayudarán a adaptarse rápidamente:
- Parámetros No Admitidos: Esta API no admite algunos parámetros de la API de OpenAI, como el parámetro de ejecución asíncrona
background. La API actualmente solo admite llamadas síncronas. - Control del Esfuerzo de Razonamiento: Utilice el parámetro
reasoning.effortpara controlar el esfuerzo de razonamiento del modelo. Para detalles de uso, consulte la descripción de este parámetro. - Límite de contexto: Para reservar espacio para las llamadas a herramientas integradas y la generación de razonamiento, el contexto de entrada máximo de la API de Responses es aproximadamente el 80% de la ventana de contexto del modelo (dejando un búfer de alrededor del 20%). Cualquier exceso se trunca automáticamente sin generar un error ni interrumpir la solicitud.
Singapore
El base_url para la configuración de llamada del SDK es https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1.
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
China (Beijing)
El base_url para la configuración de llamada del SDK: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/compatible-mode/v1/responses
EE. UU. (Virginia)
Configuración de llamada del SDK base_url: https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.us-east-1.maas.aliyuncs.com/compatible-mode/v1/responses
Germany (Frankfurt)
Configuración de llamada del SDK base_url: https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.eu-central-1.maas.aliyuncs.com/compatible-mode/v1/responses
Hong Kong (China)
Configuración de llamada del SDK base_url: https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com/compatible-mode/v1/responses
Japan (Tokyo)
Configuración de llamada del SDK base_url: https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1
Endpoint de solicitud HTTP: POST https://{WorkspaceId}.ap-northeast-1.maas.aliyuncs.com/compatible-mode/v1/responses
Reemplace {WorkspaceId} con su ID de espacio de trabajo real.
ImportanteAlibaba Cloud Model Studio ha lanzado dominios específicos de espacio de trabajo para las regiones de China (Pekín), Singapur y China (Hong Kong). Los nuevos dominios dedicados ofrecen un rendimiento superior y una mayor estabilidad para las solicitudes de inferencia. Recomendamos migrar a los nuevos dominios:
- China (Pekín): de
https://dashscope.aliyuncs.comahttps://{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapur: de
https://dashscope-intl.aliyuncs.comahttps://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com - China (Hong Kong): de
https://cn-hongkong.dashscope.aliyuncs.comahttps://{WorkspaceId}.cn-hongkong.maas.aliyuncs.com
{WorkspaceId} es su ID de espacio de trabajo, que se encuentra en la página Workspace Details de la consola de Alibaba Cloud Model Studio. El dominio existente permanece totalmente funcional.
ImportanteLa ruta URL heredada /api/v2/apps/protocols/compatible-mode/v1/responses para la API de Responses compatible con OpenAI ya no recibe mantenimiento y su funcionalidad ya no está garantizada. Migre a la nueva ruta /compatible-mode/v1/responses lo antes posible.
Cuerpo de la solicitudmodel El ID del modelo a utilizar. Modelos compatibles
ImportanteLos modelos de generación de texto que no están en la lista anterior pero que están disponibles a través de Alibaba Cloud Model Studio solo admiten funciones básicas de compatibilidad. Las capacidades de agente (herramientas integradas, etc.) son limitadas. input La entrada para el modelo. Se admiten los siguientes formatos:
Tipos de elementos del arreglo EasyInputMessage Un objeto con un Propiedades rol El rol del autor del mensaje. Valores válidos: contenido El contenido del mensaje. El contenido es una Elementos del arreglo de contenido type El tipo de contenido. Los valores válidos son text El contenido de texto. Obligatorio cuando image_url Admite una URL o datos codificados en Base64. Requerido cuando file_url La URL pública del archivo. Requerido cuando El límite de páginas PDF depende de Los siguientes tipos
use_multichannel Las entradas de audio y video utilizan el mismo formato de respuesta y eventos de transmisión que las entradas de texto. La transmisión de texto utiliza Para ejemplos de entrada de audio/video y salida de texto, consulte Qwen3.8-Omni-Flash. type Fijado como ResponseOutputMessage El mensaje de salida del modelo. Para continuar una conversación, puede pasar el objeto Propiedades type Fijado como id El identificador único del mensaje de salida, proveniente de la respuesta anterior. rol Fijado como status El estado del mensaje. Valores válidos: contenido Un arreglo de contenido, donde los elementos son objetos Propiedades type Fijado como texto El texto de respuesta. annotations Información de anotación. Llamada de función Una instrucción estructurada generada cuando el modelo decide llamar a una herramienta externa. Propiedades type Fijado como id El identificador único para la llamada de función, proveniente de la respuesta anterior. name El nombre de la función de la herramienta. arguments Los argumentos de llamada de herramienta, en formato de cadena JSON. call_id El identificador para la llamada de herramienta. Debe coincidir con el status El estado. Valores válidos: Salida de llamada de función La salida de una llamada de herramienta. En la lista de mensajes, este objeto debe seguir inmediatamente a su mensaje Propiedades type Fijado como id El identificador único para la salida de la llamada de función. call_id El identificador de llamada de herramienta debe coincidir con el output El resultado de la ejecución de la función de herramienta. status El estado. Valores válidos: Razonamiento El proceso de razonamiento del modelo. Puede pasar el elemento Propiedades type Fijado como id El identificador único para el contenido de razonamiento, proveniente de la respuesta anterior. summary El contenido del resumen de razonamiento. Propiedades type Fijado como texto El texto de resumen. status El estado. Valores válidos: Llamada de búsqueda web Un objeto de llamada de búsqueda web. Puede pasar el elemento web_search_call de la salida de la respuesta anterior a la entrada, proporcionando contexto de resultados de búsqueda en conversaciones de múltiples turnos. Propiedades type Siempre id El identificador único de la llamada de búsqueda, proveniente de la respuesta anterior. status El estado de la búsqueda. Valores válidos: action Los detalles de la acción de búsqueda. Solo se admite el tipo Propiedades type El tipo de búsqueda. Siempre queries Una lista de consultas de búsqueda. Cada elemento es una cadena. sources Una lista de fuentes de resultados de búsqueda. Propiedades type El tipo de fuente. Siempre url La URL de origen. instructions Se inserta al principio del contexto como una instrucción del sistema. Cuando se utiliza previous_response_id El ID único de la respuesta anterior. El conversation La conversación a la que pertenece la respuesta actual (consulte la API de Conversations). El historial de la conversación se incluye automáticamente como contexto. La entrada y la salida de esta solicitud se agregan a la conversación al finalizar. No se puede utilizar con stream Habilita la salida en streaming. Si se establece en store Especifica si se debe almacenar la respuesta del modelo generada para esta sesión.
tools Una matriz de herramientas que el modelo puede llamar al generar una respuesta. Admite tanto herramientas integradas como herramientas
Para Propiedades Búsqueda web Busca información actualizada en Internet. Documentación relacionada: Búsqueda web Propiedades type Fijado como Ejemplo: Accede y extrae contenido de páginas web. Debe utilizarse con la herramienta Propiedades type Fijado como Ejemplo: Ejecuta código en un entorno aislado para realizar tareas como análisis de datos. Documentación relacionada: Code Interpreter Propiedades type Fijado como Ejemplo: Busca imágenes basándose en una descripción de texto. Documentación relacionada: Búsqueda de texto a imagen Propiedades type Fijado como Ejemplo: Busca imágenes similares o relacionadas basándose en una imagen de entrada. La entrada debe incluir la URL de la imagen. Documentación relacionada: Image-to-Image Search Propiedades type Fijado como Ejemplo: Realiza la recuperación de conocimientos buscando en una base de conocimientos especificada. Documentación relacionada: Recuperación de conocimientos Propiedades type Fijado como vector_store_ids El ID de la base de conocimientos para buscar. Actualmente, solo se puede proporcionar un ID de base de conocimientos. Ejemplo: Llama a un servicio externo a través del Protocolo de Contexto del Modelo (MCP). Documentación relacionada: MCP Propiedades type Fijado como server_protocol El protocolo de comunicación con el servicio MCP, como server_label Una etiqueta utilizada para identificar el servicio MCP. server_description Una descripción del servicio. Ayuda al modelo a comprender su función y cuándo utilizarlo. server_url La URL del endpoint del servicio MCP. headers Encabezados de solicitud, utilizados para transportar información como la autenticación (por ejemplo, Ejemplo: Permite al modelo llamar a una función definida por el desarrollador. Cuando el modelo determina que es necesario llamar a una herramienta, la respuesta devuelve un elemento de salida de tipo Propiedades type Debe establecerse en name El nombre de la herramienta. Solo puede contener letras, dígitos, guiones bajos ( description Una descripción de la herramienta, que ayuda al modelo a decidir cuándo y cómo llamarla. parameters La definición de parámetros para la herramienta, que debe ser un objeto JSON Schema válido. Si
Ejemplo: tool_choice Controla cómo el modelo selecciona y llama a las herramientas. Este parámetro admite dos formatos: modo de cadena y modo de objeto. Modo cadena
Restringe el modelo a un conjunto específico de herramientas para su selección y llamada. Propiedades mode
tools Una lista de definiciones de herramientas que el modelo tiene permitido llamar. type El tipo de configuración de herramienta. Fijado en parallel_tool_calls Especifica si se habilita la llamada a herramientas en paralelo. Para obtener más información, consulte Llamada a herramientas en paralelo.
Valores válidos:
temperature La temperatura de muestreo, que controla la diversidad del texto generado. Valores más altos hacen que la salida sea más aleatoria y diversa, mientras que valores más bajos la hacen más enfocada y determinista. Rango de valores: [0, 2) Tanto top_p El umbral de probabilidad para el muestreo top-p, que controla la diversidad del texto generado. Valores más altos hacen que la salida sea más aleatoria y diversa, mientras que valores más bajos la hacen más enfocada y determinista. Rango de valores: (0, 1.0] Tanto enable_thinking Habilita o deshabilita el modo de razonamiento. Cuando está habilitado, el modelo realiza un paso de razonamiento antes de responder. El proceso de razonamiento se devuelve como un elemento de salida de tipo Valores válidos:
Para los valores predeterminados de diferentes modelos, consulte Modelos compatibles.
reasoning Controla el esfuerzo de razonamiento del modelo. El modelo realiza un paso de razonamiento antes de responder, y el proceso de razonamiento se devuelve a través de un elemento de salida de tipo Propiedades effort Admite 7 niveles incrementales:
Para
ocr_options Parámetros de tareas integradas de OCR. Solo aplicable al modelo Al analizar archivos PDF, el valor de
max_output_tokens Limita el número de tokens en la salida generada.
El valor mínimo para los modelos listados anteriormente es 16. Cuando el recuento de tokens generados alcanza el límite configurado, la generación se detiene anticipadamente y el estado es | Llamada básicaSalida por secuenciasConversación de múltiples turnosHerramientas integradasLlamada a funcionesComprensión de documentosCaché de sesiónPara habilitar el almacenamiento en caché de sesión, configure El almacenamiento en caché implícito automático se describe por separado en Caché de contexto. |
Objeto de respuesta (salida sin transmisión)id Un identificador único para esta respuesta, un UUID. Este ID es válido por 7 días y puede utilizarse en el parámetro created_at La marca de tiempo Unix (en segundos) para esta solicitud. object El tipo de objeto, que siempre es status El estado de la generación de respuesta. Valores válidos:
model El ID del modelo utilizado para generar la respuesta. output Una matriz de elementos de salida generados por el modelo. El tipo y el orden de los elementos en la matriz dependen de la respuesta del modelo. Propiedades de los elementos del arreglo type El tipo de elemento de salida. Valores válidos:
id El identificador único del elemento de salida. Todos los tipos de elementos de salida contienen este campo. role El rol del mensaje es siempre status El estado del elemento de salida. Valores válidos: name El nombre de la herramienta o función. Este parámetro está presente cuando Para Para arguments Los parámetros para la llamada a la herramienta, en formato de cadena JSON. Este parámetro está presente cuando
call_id El ID único para la llamada de función. Este parámetro se incluye solo cuando content La matriz de contenido del mensaje. Este parámetro está presente solo si Propiedades de los elementos del arreglo type El tipo de contenido. El valor está fijado en text El contenido de texto generado por el modelo. annotations El arreglo de anotaciones de texto. Por lo general, es un arreglo vacío. summary Una matriz de resúmenes de razonamiento. Este campo está presente solo cuando acción La información sobre la acción de búsqueda. Este parámetro está presente solo cuando Propiedades query Las palabras clave de la consulta de búsqueda. type El tipo de búsqueda. El valor siempre es sources Una lista de fuentes de búsqueda. Cada elemento contiene los campos code El código generado y ejecutado por el modelo. Existe solo cuando outputs La matriz de salida de ejecución de código. Esto está presente solo cuando container_id El identificador del contenedor para el intérprete de código. Este parámetro está presente solo cuando goal Una descripción de la información a extraer de la página web. Este parámetro está disponible solo cuando output La salida de la llamada de herramienta. La salida es una cadena.
urls La lista de URL de las páginas web extraídas. Este parámetro está disponible solo cuando server_label La etiqueta para el servicio MCP. Aparece solo cuando queries Una lista de consultas para la recuperación de la base de conocimientos. Este parámetro existe solo cuando results Una matriz de resultados de búsqueda de la base de conocimientos. Este parámetro está presente solo cuando Propiedades de los elementos del arreglo file_id El ID de archivo del documento coincidente. filename El nombre de archivo del documento coincidente. score La puntuación de relevancia de la coincidencia. El valor oscila entre 0 y 1. Un valor mayor indica una mayor relevancia. text El fragmento de contenido del documento coincidente. usage Información sobre el consumo de tokens para esta solicitud. Propiedades input_tokens El número de tokens en la entrada. Notas adicionales output_tokens El número de tokens en la salida del modelo. total_tokens El número total de tokens consumidos es la suma de input_tokens_details Una clasificación detallada de los tokens de entrada. Propiedades cached_tokens El número de tokens que acertaron en la caché. Para obtener más información, consulte caché de contexto. output_tokens_details Un desglose detallado de los tokens de salida. Propiedades reasoning_tokens El número de tokens de razonamiento. x_details Una matriz de detalles de facturación para la solicitud. Proporciona un desglose más granular de los tokens multimodales que el campo Propiedades input_tokens El número de tokens en la entrada. Notas adicionales output_tokens El número de tokens en la salida del modelo. total_tokens El número total de tokens consumidos es la suma de x_billing_type El valor está fijado en image_tokens El número de tokens para la entrada de imagen. Este campo se devuelve cuando la entrada incluye una imagen y es equivalente a input_tokens_details Un desglose de los tokens de entrada. Los campos dependen del modelo y las modalidades de entrada. Para entrada de audio, Propiedades text_tokens El número de tokens para la entrada de texto. image_tokens El número de tokens para la entrada de imagen. audio_tokens El número de tokens de entrada de audio en output_tokens_details Un desglose detallado de los tokens de salida. Este campo tiene un campo Propiedades reasoning_tokens El número de tokens para el proceso de razonamiento. text_tokens El número de tokens para la salida de texto. Este campo se devuelve para entradas multimodales. plugins Estadísticas para llamadas de herramientas integradas. Este campo se devuelve cuando se utiliza una herramienta integrada como Propiedades web_search Estadísticas de las llamadas de búsqueda web. Propiedades count El número de veces que se llamó a la búsqueda web en esta respuesta. prompt_tokens_details Detalles de caché para tokens de entrada. Este campo se devuelve cuando la caché de sesión está habilitada. Puede devolver un objeto vacío si la entrada incluye una imagen pero resulta en un fallo de caché. Propiedades cached_tokens El número de tokens que coincidieron con la caché. cache_creation_input_tokens El número de tokens utilizados para crear una nueva caché en esta solicitud. cache_creation Detalles sobre la creación de caché. Propiedades ephemeral_5m_input_tokens El número de tokens utilizados para crear una nueva caché efímera de 5 minutos. cache_type El tipo de caché. El valor está fijado en x_tools Estadísticas sobre el uso de herramientas. Esto contiene el número de veces que se llama a cada herramienta integrada. Ejemplo: error Se devuelve un objeto de error cuando el modelo no logra generar una respuesta. De lo contrario, el valor es tools Repite el contenido completo del parámetro tool_choice Repite el valor del parámetro | |
Objeto de fragmento de respuesta (salida en streaming)La salida por flujo devuelve una serie de objetos JSON. Cada objeto incluye un campo type El identificador del tipo de evento. Los valores posibles incluyen:
sequence_number El número de secuencia del evento, comenzando en 0 e incrementándose con cada evento. Utilice este número para procesar los eventos en el orden correcto. response El objeto de respuesta. Aparece en los eventos item Un objeto de elemento de salida. Aparece en los eventos Propiedades id Un identificador único para el elemento de salida (por ejemplo, type El tipo del elemento de salida. Valores posibles: role El rol del mensaje, que siempre es status Estado de generación. En un evento content Una matriz de contenido de mensaje. En el evento part El objeto de parte de contenido. Aparece en los eventos Propiedades type El tipo de la parte de contenido, que siempre es text Contenido de texto. Es una cadena vacía en el evento annotations Un arreglo de anotaciones de texto. Generalmente un arreglo vacío. logprobs Probabilidades logarítmicas de tokens. Este campo actualmente siempre devuelve delta El segmento de texto incremental. Este campo aparece en el evento text El contenido de texto completo. Este campo aparece en el evento item_id El identificador único para el elemento de salida. Utilice este ID para correlacionar eventos que pertenecen al mismo elemento. output_index El índice del elemento de salida en el arreglo content_index El índice de la parte de contenido en el arreglo | |
FAQ
P: ¿Cómo paso el contexto para una conversación de múltiples turnos?R: Al realizar una nueva solicitud de conversación, pase el id de la respuesta exitosa anterior del modelo como el parámetro previous_response_id.
R: El SDK oficial de OpenAI puede generar campos adicionales definidos por el protocolo de OpenAI. Nuestro servicio no admite estos campos, por lo que normalmente son null. Concéntrese únicamente en los campos descritos en este tema.