Skip to main content

Referencia de la API DashScope para aplicaciones

Parámetros de entrada y salida para llamar a aplicaciones de Model Studio (Agente, Flujo de Trabajo) a través de la API DashScope, con ejemplos para escenarios típicos.

Este tema es aplicable únicamente a la región de Singapur.
Guías relacionadas Invocación de aplicación.

Requisitos previos

Complete las siguientes tareas:
  1. Crear una aplicación: Vaya a Gestión de Aplicaciones para crear una aplicación de Model Studio y obtener su ID de aplicación.
  2. Obtener una clave de API: Obtenga su clave de API en Gestión de Claves y configure la clave de API como variable de entorno.
  3. Instalar el SDK (opcional): Si utiliza un SDK para realizar llamadas, instale el SDK de DashScope para su lenguaje de programación.

Métodos de invocación

  • Llamada de API HTTP URL de solicitud: POST https://dashscope-intl.aliyuncs.com/api/v1/apps/APP_ID/completion
    Reemplace APP_ID con su ID de aplicación real.
  • Llamada de SDK SDK de Python/Java: El endpoint correcto está configurado de forma predeterminada. Endpoint personalizado: Configúrelo mediante el parámetro base_url.

Cuerpo de la solicitud

app_idstring(obligatorio)ID de aplicación.Obtenga el ID de la aplicación desde la tarjeta de la aplicación en la página de Gestión de Aplicaciones.
En el SDK de Java, esto es appId. Al llamar mediante HTTP, coloque su ID de aplicación real en la URL, reemplazando APP_ID.
promptstring(obligatorio)Entrada del usuario que guía a la aplicación para generar una respuesta.
Al llamar mediante HTTP, coloque prompt en el objeto input.
session_idstring (opcional)Identificador del historial de conversación.Pase session_id para incluir automáticamente el historial de conversaciones almacenado en la nube. Requiere prompt.Caduca después de 1 hora de inactividad.
En el SDK de Java, esto es setSessionId. Al llamar mediante HTTP, coloque session_id en el objeto input.
mensajesarray(opcional)Contexto de conversación pasado al modelo, organizado en orden cronológico.Para conversaciones de múltiples turnos, pase messages en lugar de prompt o session_id.Si pasa tanto session_id como messages, el modelo utiliza el contenido en messages e ignora session_id y prompt.
Al llamar mediante HTTP, coloque messages en el objeto input.
Para utilizar este parámetro, su versión del SDK de Python Dashscope debe ser al menos 1.20.14, y su versión del SDK de Java Dashscope debe ser al menos 2.17.0.

Tipos de mensajes

Mensaje del sistemaobject (opcional)Mensaje del sistema que establece el rol del modelo, el tono, los objetivos de la tarea o las restricciones. Generalmente se coloca primero en el arreglo messages.
contenidostring(obligatorio)Instrucción del sistema que define el rol del modelo, las pautas de comportamiento, el estilo de respuesta y las restricciones de la tarea.rolstring(obligatorio)Rol del mensaje del sistema, fijado como system.
Mensaje de usuarioobject(obligatorio)Mensaje de usuario que pasa preguntas, instrucciones o contexto al modelo.
contenidostring(obligatorio)Contenido del mensaje.
textostring(obligatorio)Texto de entrada.
rolstring(obligatorio)Rol del mensaje de usuario, fijado como user.
Mensaje del asistenteobject (opcional)Respuesta del modelo. Normalmente se utiliza como contexto que se pasa de nuevo al modelo en conversaciones de múltiples turnos.
contenidostring(obligatorio)Contenido de texto de la respuesta del modelo.rolstring(obligatorio)Rol del mensaje del asistente, fijado como assistant.
espacio de trabajo string (opcional)Identificador del espacio de trabajo. Documentación relacionada: Obtener ID del espacio de trabajo.Solo necesita pasar el workspace ID al invocar aplicaciones en un subespacio de trabajo.
Al llamar mediante HTTP, especifique el encabezado X-DashScope-WorkSpace.
stream boolean (opcional) El valor predeterminado es FalseHabilitar salida en streaming.Establezca en True para mejorar la experiencia de lectura y reducir el riesgo de tiempo de espera.Valores de parámetro:
  • False (predeterminado): El modelo devuelve todo el contenido de una sola vez después de que se completa la generación.
  • True (recomendado): El modelo transmite el contenido de forma incremental. Lea los fragmentos en tiempo real para ensamblar la respuesta completa.
Para implementar la salida de transmisión con el SDK de Java, utilice la interfaz streamCall. Para implementar la salida de transmisión mediante HTTP, configure el encabezado X-DashScope-SSE en enable.
incremental_output boolean (opcional) El valor predeterminado es FalseHabilite la salida incremental en modo streaming.Establezca en True para mejorar la experiencia de lectura.Valores de parámetro:
  • False (predeterminado): Cada salida contiene la secuencia completa generada hasta el momento.
I
I like
I like apple
I like apple.
  • True (recomendado): Salida incremental. Cada fragmento contiene solo contenido nuevo. Lea los segmentos en tiempo real para ensamblar el resultado completo.
I
like
apple
.
En el SDK de Java, esto es incrementalOutput. Al llamar mediante HTTP, coloque incremental_output en el objeto parameters.
flow_stream_mode string (opcional) El valor predeterminado es full_thoughtsModo de salida en streaming para la Aplicación de Flujo de Trabajo.Valores de parámetro:
  • message_format (recomendado): Devuelve los resultados de nodos específicos (ya sea un nodo de Salida o un nodo Final) en el campo message.
    En la aplicación de consola, active el interruptor de Transmisión para el nodo objetivo a fin de devolver resultados en modo de transmisión. Si está desactivado, el resultado final del nodo se devuelve de una sola vez.
    En el SDK de Java, esto es FlowStreamMode.MESSAGE_FORMAT.
  • full_thoughts (predeterminado): Devuelve los resultados de todos los nodos en el campo thoughts.
    Al usar este modo, también debe establecer el parámetro has_thoughts en True.
    En el SDK de Java, esto es FlowStreamMode.FULL_THOUGHTS.
  • agent_format: Devuelve los resultados de nodos especificados (nodos LLM o nodos finales) en el campo text. En la aplicación de consola, active el interruptor de Respuesta para el nodo objetivo a fin de devolver resultados en modo de transmisión.
    No utilice este modo con nodos paralelos, ya que puede causar mezcla de contenido. Asegúrese de que los nodos activados tengan un orden de ejecución claro.
    En el SDK de Java, esto es FlowStreamMode.AGENT_FORMAT.
Su versión del SDK de Python debe ser al menos 2.0.1, y su versión del SDK de Java debe ser al menos 2.21.0. Al llamar mediante HTTP, coloque flow_stream_mode en el objeto parameters.
biz_paramsobject (opcional)Pase parámetros para variables personalizadas, nodos o complementos.
En el SDK de Java, esto es bizParams. Al llamar mediante HTTP, coloque biz_params en el objeto input.
Para la Aplicación de Flujo de Trabajo, pase las variables personalizadas para el nodo de inicio directamente, por ejemplo:
biz_params = {"city": "Hangzhou"}
Para la Aplicación Agente, pase las variables de prompt o las variables del complemento utilizando los siguientes campos:

Propiedades

user_defined_params object (opcional)Parámetros de plugin personalizados.Los complementos no pueden duplicarse. Máximo: 10.

Propiedades

tool_idstring (opcional)ID del complemento, disponible en la tarjeta del complemento.${plugin_params}string (opcional)El objeto más interno contiene múltiples pares clave-valor. Cada par clave-valor representa un nombre de parámetro definido por el usuario y su valor especificado. Por ejemplo:
"article_index": 2
Pasos de uso:
  1. Asocie el complemento especificado con su aplicación y Publique la aplicación.
  2. Pase la información del complemento a través de este parámetro durante las llamadas a la API.
Puede proporcionar múltiples pares clave-valor, donde cada clave es el TOOL_ID del complemento y el valor es el objeto de parámetro requerido por ese complemento. Ejemplo:
"user_defined_params": {
        "<TOOL_ID>": {
            "article_index": 2},
        "<TOOL_ID>": {
            "article_index": 8}
        }
user_defined_tokens object (opcional)Autenticación a nivel de usuario para complementos personalizados.Los complementos no pueden duplicarse. Máximo: 10.

Propiedades

tool_idstring (opcional)ID del complemento, disponible en la tarjeta del complemento. Pase a través del campo <TOOL_ID>.user_token string (opcional)Pase la información de autenticación de usuario requerida por este complemento, como el valor real de DASHSCOPE_API_KEY.
Pasos de uso:
  1. Asocie el complemento especificado con su aplicación y Publique la aplicación.
  2. Pase la información de autenticación a nivel de usuario del complemento a través de este parámetro durante las llamadas a la API.
Puede proporcionar múltiples pares clave-valor, donde cada clave es el TOOL_ID del complemento y el valor es el objeto user_token.
has_thoughts boolean (opcional) El valor predeterminado es FalseControla si la invocación de complementos y la recuperación de conocimiento aparecen en el campo thoughts.Valores de parámetro:
  • True: Salida incluida.
  • False (predeterminado): Salida no incluida.
En el SDK de Java, esto es hasThoughts. Al llamar mediante HTTP, coloque has_thoughts en el objeto parameters.
rag_options object (opcional)Configure los parámetros de recuperación, incluida la recuperación de bases de conocimiento o documentos específicos.
Solo la Aplicación Agente admite este parámetro.
En el SDK de Java, esto es ragOptions. Al llamar mediante HTTP, coloque rag_optionsen el objeto parameters.

Propiedades

pipeline_ids array(obligatorio)Una lista que contiene uno o más IDs de base de conocimiento. Máximo de 5.Recupera todos los documentos dentro de las bases de conocimiento especificadas.Cómo obtenerlo:
  • Página de Base de Conocimiento para obtener el ID de la base de conocimiento;
  • O bien a través de la API CreateIndex (admite solo bases de conocimiento no estructuradas), que devuelve Data.Id.
En el SDK de Java, esto es pipelineIds.
file_idsarray(opcional)Una lista que contiene uno o más IDs de documentos no estructurados. Máximo de 5.Recupera documentos no estructurados dentro de las bases de conocimiento especificadas.Al pasar IDs de documentos, también debe pasar el ID de la base de conocimiento a la que pertenecen estos documentos en el campo pipeline_ids.Cómo obtenerlo:
En el SDK de Java, esto es fileIds.
metadata_filterobject (opcional)Filtre documentos no estructurados especificando uno o más pares clave-valor de metadatos dentro de la base de conocimiento especificada.Requisitos previos:Al pasar metadatos, también debe pasar el ID de la base de conocimiento a la que pertenecen dichos metadatos en el campo pipeline_ids.Cómo verlo:
  • Visite la página de Base de Conocimiento, haga clic en View DetailsMetadata Information en la tarjeta de la base de conocimiento para verlo.
  • O bien obtenerlo a través de la API ListChunks.
Este objeto consta de uno o más pares clave-valor:
  • Clave: tipo String, que representa el nombre de los metadatos.
  • Valor:
    • Coincidencia exacta: El valor es un String, lo que significa que solo se recuperan los documentos cuyo valor de campo coincide exactamente con esta cadena.
      • Ejemplo: "author": "John.Doe"
    • Coincidencia "OR" de valores múltiples: El valor es un Array (arreglo) o List (lista) que contiene múltiples Strings. Esto significa que se recuperan los documentos cuyo valor de campo coincide con cualquier valor en el arreglo (lógica OR).
      • Ejemplo: "source": ["internal_wiki", "public_docs"]
Lógica de combinación: Las diferentes claves utilizan lógica "AND". Por ejemplo, "author": "John.Doe", "source": ["internal_wiki", "public_docs"] significa filtrar documentos escritos por "John.Doe" Y obtenidos de "internal_wiki" O "public_docs".
En el SDK de Java, esto es metadataFilter.
etiquetas array (opcional)Una lista que contiene una o más etiquetas para documentos no estructurados.Puede recuperar documentos no estructurados con esta etiqueta.Cómo verlo:
  • Conversación de un solo turno
  • Conversación de múltiples turnos
  • Pasar parámetros
  • Salida de transmisión
  • Recuperación de base de conocimiento
  • Python
  • Java
  • HTTP
Ejemplo de solicitud
import os
import dashscope
from dashscope.v2 import DashScopeError

# La siguiente es la configuración de la región de Singapur. Sustituya {WorkspaceId} por el ID de su workspace. El valor de region varía según la región.
client = dashscope.Client(
    # Si no utiliza una variable de entorno, configure su API key directamente (por ejemplo, api_key="sk-xxx"). No se recomienda codificar la API key en el código en entornos de producción, para reducir el riesgo de filtración de la API key.
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)
try:
    response = client.apps.completions.create(
        app_id='APP_ID',  # Sustituya por el ID real de su aplicación
        prompt='Who are you?')
    print(response.text)
except DashScopeError as e:
    print(f'request_id={e.request_id}')
    print(f'code={e.code}')
    print(f'message={e.message}')
    print(f'Consulte la documentación: https://www.alibabacloud.com/help/model-studio/developer-reference/error-code')

Objeto de respuesta

status_code stringCódigo de estado HTTP.200 indica éxito; otros códigos indican fallo.En caso de fallo, revise code para el código de error y message para los detalles.
El SDK de Java no devuelve este parámetro. En caso de fallo, lanza una excepción que contiene el contenido de status_code y message.
request_id stringID único para esta invocación.
El SDK de Java devuelve esto como requestId.
code stringCódigo de error. Vacío en caso de éxito.
Solo devuelto por el SDK de Python.
message stringDetalles del error. Vacío en caso de éxito.
Solo devuelto por el SDK de Python.
output objectResultado de invocación.

propiedades de output

text stringContenido de respuesta del modelo.finish_reason stringMotivo por el que finalizó la respuesta.stop significa finalización natural (se encontró un marcador preestablecido), null significa interrupción forzada (por ejemplo, se alcanzó el límite máximo de longitud o se detuvo manualmente).session_idstringID único para la conversación actual.Pase esto en solicitudes posteriores para llevar registros históricos de conversación.pensamientosarrayCuando configura el parámetro has_thoughts en True durante la invocación, puede ver la invocación de complementos, los procesos de recuperación de conocimiento o el proceso de pensamiento del modelo de pensamiento profundo en thoughts.
pensamiento stringProceso de pensamiento del modelo.Cuando selecciona un modelo de pensamiento profundo en la Aplicación Agente de su consola y la publica correctamente, si configura el parámetro has_thoughts en True durante la invocación de la API, el proceso de pensamiento del modelo se devolverá en este campo.reasoningContentstringProceso de pensamiento del modelo.Cuando selecciona un modelo de pensamiento profundo en la Aplicación de Flujo de Trabajo de su consola y la publica correctamente, si configura el parámetro has_thoughts en True durante la invocación de la API, el proceso de pensamiento del modelo se devolverá en este campo.action_type stringTipo de paso de ejecución devuelto por el modelo. Por ejemplo, API significa ejecutar un complemento de API, agentRag significa ejecutar recuperación de conocimiento, y reasoning significa ejecutar el proceso de pensamiento del modelo de pensamiento profundo.action_name stringNombre de la acción ejecutada, como recuperación de conocimiento, complemento de API o proceso de pensamiento.acción stringPasos de ejecución.action_input_stream stringResultado en streaming de los parámetros de entrada.action_input stringParámetros de entrada del plugin.observación stringProceso de recuperación o ejecución del complemento.
doc_references arrayDocumentos referenciados que el modelo citó.En la Aplicación Agente de su consola de Model Studio, active el interruptor de Mostrar Fuente y Publique la aplicación para que doc_references pueda contener información válida.
index_id stringÍndice del documento referenciado, por ejemplo, [1].title stringTítulo del segmento de texto referenciado.doc_id stringID del documento referenciado.doc_name stringNombre del documento referenciado.text stringContenido de texto específico referenciado por el modelo.biz_id stringIdentificador de asociación empresarial referenciado por el modelo.images arrayLista de URL de imágenes referenciadas por el modelo.
usage objectUso de tokens para esta solicitud.

propiedades de usage

modelsarrayInformación del modelo para esta invocación.
model_id stringID del modelo utilizado por esta aplicación.input_tokens integerRecuento de tokens de entrada.output_tokens integerRecuento de tokens de salida.
Ejemplo de respuesta de conversación de un solo turno
{
    "output": {
        "finish_reason": "stop",
        "session_id": "6105c965c31b40958a43dc93c28c7a59",
        "text": "I am Qwen, an AI assistant developed by Alibaba Cloud. I'm designed to answer various questions, provide information, and converse with users. How can I help you?"
    },
    "usage": {
        "models": [
            {
                "output_tokens": 36,
                "model_id": "qwen-plus",
                "input_tokens": 74
            }
        ]
    },
    "request_id": "f97ee37d-0f9c-9b93-b6bf-bd263a232bf9"
}
Ejemplo de respuesta de base de conocimiento especificadaPara generar información de documentos referenciados a partir de documentos recuperados, abra la Aplicación Agente de su aplicación, haga clic en Retrieve Configuration, active Show Source y Publish la aplicación.
{
    "text": "Based on your budget, I recommend considering the Bailian Zephyr Z9. This phone is lightweight and portable, featuring a 6.4-inch screen with 1080 x 2340 pixel resolution, paired with 128GB storage and 6GB RAM, making it perfect for daily use<ref>[1]</ref>. Additionally, it comes with a 4000mAh battery and a 30x digital zoom lens to capture distant details, priced between 2499-2799 yuan, fully meeting your budget requirements<ref>[1]</ref>.",
    "finish_reason": "stop",
    "session_id": "6c1d47fa5eca46b2ad0668c04ccfbf13",
    "thoughts": null,
    "doc_references": [
        {
            "index_id": "1",
            "title": "Bailian Phone Product Introduction",
            "doc_id": "file_7c0e9abee4f142f386e488c9baa9cf38_10317360",
            "doc_name": "Bailian Series Phone Product Introduction",
            "doc_url": null,
            "text": "【Document Name】:Bailian Series Phone Product Introduction\n【Title】:Bailian Phone Product Introduction\n【Content】:Reference Price: 5999- 6499. Bailian Ace Ultra ——For Gamers: Equipped with a 6.67-inch 1080 x 2400 pixel screen, built-in 10GB RAM and 256GB storage, ensuring smooth gaming. Bailian Ace Ultra ——For Gamers: Equipped with a 6.67-inch 1080 x 2400 pixel screen, built-in 10GB RAM and 256GB storage, ensuring smooth gaming. 5500mAh battery with liquid cooling system keeps your device cool during extended gaming sessions. High-dynamic dual speakers enhance immersive audio for gaming. Reference Price: 3999- 4299. Bailian Zephyr Z9 ——Art of Slim Design: Lightweight 6.4-inch 1080 x 2340 pixel design, paired with 128GB storage and 6GB RAM, handles daily tasks effortlessly. 4000mAh battery ensures all-day usage, while the 30x digital zoom lens captures distant details without compromising on power. Reference Price: 2499- 2799. Bailian Flex Fold+ ——New Era of Foldable Phones: Combines innovation and luxury with a 7.6-inch 1800 x 2400 pixel main screen and 4.7-inch 1080 x 2400 pixel outer screen, supporting multi-angle free-stop design for different scenarios. 512GB storage, 12GB RAM, plus a 4700mAh battery and UTG ultra-thin flexible glass, ushering in a new chapter for foldable phones. Additionally, this phone supports Dual SIM Dual Standby and satellite calls, keeping you connected worldwide. Reference Retail Price: 9999- 10999.\n",
            "biz_id": null,
            "images": [

            ],
            "page_number": [
                0]
        }]
}
Ejemplo de respuesta de errorCuando una solicitud falla, la respuesta incluye detalles del error a través de code y message.Este ejemplo muestra una respuesta de error para una API-KEY no válida.
request_id=1d14958f-0498-91a3-9e15-be477971967b,
code=401,
message=Invalid API-key provided.

Límites de tasa

El QPM predeterminado (consultas por minuto) para una sola aplicación es 15,000.

Códigos de error

Si la invocación falla y devuelve un error, consulte Información de errores para ver las soluciones.