Alibaba Cloud Model Studio:Complementos personalizados

Crear un complemento personalizado

Paso 1: Crear un complemento

1. Vaya a la página Complementos y haga clic en Create Plugin.

2. Introduzca la información del complemento.

   Plug-in Name: Introduzca un nombre descriptivo. Se admiten chino e inglés. Ejemplo: Prueba de herramienta de consulta de acuerdos de dormitorio

   Descripción del complemento: Describa brevemente las características y el propósito del complemento en lenguaje natural. Esta descripción ayuda al modelo a decidir cuándo usar el complemento. Ejemplo: Consulta el contenido de una entrada específica de acuerdo de dormitorio basada en el índice numérico de entrada.

   Plug-in URL: El punto de conexión de acceso del complemento. Ejemplo: https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run Model Studio trata las diferentes rutas bajo el mismo dominio como APIs distintas. Estas rutas corresponden a la Ruta de la herramienta que configura al crear una herramienta. Las herramientas dentro del mismo complemento comparten un nombre de dominio, pero la ruta de cada herramienta se asigna a una API única. Por ejemplo, un complemento contiene dos API: Consulta: https://xxx.com/query Eliminar: https://xxx.com/delete En este ejemplo, https://xxx.com es la URL del complemento, mientras que /query y /delete son los valores de la Ruta de la herramienta. Esto indica que el complemento contiene dos herramientas.

   Si se requiere autenticación, active el interruptor Habilitar autenticación e introduzca la configuración de autenticación.

   Parámetros de autenticación

   Headers (Opcional)	Si se requiere autenticación, puede pasar la información de autenticación en un encabezado personalizado.
   Enable Authentication (Opcional)	Determina si una aplicación debe proporcionar autenticación para invocar su complemento personalizado. Esto depende de la política de seguridad de su proveedor de API.
   Authentication Type	Existen dos métodos de autenticación: autenticación a nivel de servicio y autenticación a nivel de usuario. Location: Puede colocar la información de autenticación en el encabezado de la solicitud o en la cadena de consulta. Header: Esta opción coloca la información de autenticación en el encabezado Authorization de la solicitud HTTP, manteniéndola oculta en la URL. Query: Esta opción coloca la información de autenticación en la URL. Por ejemplo: https://example.com?api_key=123456. Nombre del parámetro: Si coloca la información de autenticación en la cadena de consulta, especifique el nombre del parámetro utilizado para la autenticación, como api_key. Si la coloca en el encabezado, el parámetro es Authorization por defecto. Type: basic: No agrega ningún prefijo al token que proporciona. bearer: Agrega el prefijo Bearer al token. appcode: Agrega el prefijo APPCODE al token. El prefijo se incluye en el campo de autenticación. Por ejemplo, si selecciona bearer, el encabezado Authorization se convierte en Authorization: Bearer <YOUR_TOKEN>. Token (para autenticación a nivel de servicio): El token de autenticación del proveedor de la API, como una clave de API.

3. Después de completar el formulario, haga clic en Confirm Create Plug-inCreate Tool o haga clic en Continue to Add Tool.

Paso 2: Crear una herramienta

1. Introduzca la información de la herramienta, configure los parámetros de entrada y salida, y defina cualquier configuración avanzada.

   En este ejemplo, introduzca "Herramienta de consulta de reglas de dormitorio" para Nombre de la herramienta y "Consulta el contenido de una regla de dormitorio específica basada en el índice numérico de entrada" para Descripción de la herramienta. Establezca la Ruta de la herramienta en /article, seleccione POST para el Request Method y seleccione application/json para el Submission Method. Para el parámetro de entrada, establezca el nombre del parámetro en article_index, la descripción del parámetro en "índice" y el tipo en Número. Este parámetro se pasa en el Cuerpo, es obligatorio y su método de paso es Reconocimiento LLM. Para el parámetro de salida, establezca el nombre del parámetro en article, la descripción del parámetro en "contenido de la regla de dormitorio" y el tipo en Cadena. En la configuración avanzada, la consulta de entrada del usuario es "Consultar el contenido de la regla de dormitorio correspondiente basada en el valor de índice de entrada", y el valor del parámetro de entrada article_index es 5.

   Parámetros de la herramienta

   Información de la herramienta

   Tool Name	Introduzca un nombre descriptivo. Se admiten chino e inglés.
   Tool Description	Una breve descripción de las características y casos de uso de la herramienta. Esto ayuda al modelo a decidir cuándo llamar a la herramienta. Utilice lenguaje natural y proporcione ejemplos siempre que sea posible.
   Tool Path	La ruta relativa a la Plug-in URL. La ruta debe comenzar con una barra diagonal (/). El sistema anexa esta ruta a la Plug-in URL para construir la URL de solicitud completa.
   Request Method	Seleccione GET o POST como método de solicitud para llamar a la API.
   Submission Method	El tipo de codificación para el cuerpo de la solicitud. application/json: El contenido del cuerpo son datos con formato JSON. application/x-www-form-urlencoded: Codifica los datos del formulario como pares clave-valor. Este método de codificación se aplica a las solicitudes POST. Codifica los datos del formulario en pares clave-valor, separa los pares con ampersands (&) y separa las claves de los valores con signos iguales (=). Luego, los datos se codifican en URL, lo que convierte los caracteres especiales en un signo de porcentaje (%) seguido de dos dígitos hexadecimales. Por ejemplo, un espacio se codifica como %20, & como %26 y = como %3D. Ejemplo: name=John Doe&age=25 se codifica como name=John%20Doe&age=25.

   Configurar parámetros de entrada y salida

   Configure Input Parameters	Haga clic en Add Input Parameter para configurar los parámetros.
   	Nombre del parámetro: Utilice un nombre descriptivo para ayudar al modelo a comprender qué representa el parámetro. Por ejemplo, city.
   	Descripción del parámetro: Una descripción concisa y precisa de la función del parámetro de entrada. Esto ayuda al modelo a comprender mejor cómo recuperar el valor del parámetro. Por ejemplo, para un parámetro llamado date, puede describirlo como una fecha y también especificar su formato, como yyyy-MM-dd.
   	Type: El tipo de datos del parámetro. Las subpropiedades de un Object no pueden estar vacías. Haga clic en el icono al final de la fila del objeto para agregar una subpropiedad.
   	Método de paso: Define cómo se pasa el valor del parámetro. Esta configuración es crítica para el funcionamiento correcto. LLM Recognition: El modelo extrae el valor del parámetro de la entrada del usuario. Transferencia directa de negocio: El sistema pasa el valor del parámetro directamente desde una fuente externa sin procesarlo ni modificarlo. Cuando invoca una aplicación utilizando el SDK de DashScope o una API HTTP, el sistema pasa los parámetros de entrada del tipo business pass-through a la aplicación utilizando biz_params y user_defined_params. Para más información, consulte Pasar parámetros a una aplicación.
   Configure Output Parameters	Haga clic en Add Output Parameters y configure los parámetros. Todos los parámetros son required. El modelo utiliza las definiciones de los parámetros de salida para filtrar y reestructurar la respuesta de la API según la consulta del usuario, y luego devuelve la respuesta final. Al igual que los parámetros de entrada, los parámetros de salida deben describirse de manera concisa y precisa, con una anidación mínima. Tanto los métodos de solicitud GET como POST admiten el tipo Object para los parámetros. Sin embargo, las subpropiedades de un Object no pueden estar vacías. Haga clic en el icono al final de la fila del objeto para agregar una subpropiedad.

   Configuración avanzada (Opcional)

   Advanced Configuration	Proporcione ejemplos de llamada para ayudar al modelo a evitar llamadas de herramientas omitidas o incorrectas. Si los parámetros de entrada son complejos y el modelo podría construirlos incorrectamente, proporcionar ejemplos mejora la precisión de la invocación.
   	Valor: Especifica los parámetros de invocación que espera que el modelo genere a partir de la consulta de un usuario. Por ejemplo, para la entrada del usuario "¿Cuál es el clima en Hangzhou mañana?", los parámetros esperados son {"city": "Hangzhou", "date": "2025-04-25"}.

2. Después de completar la configuración, haga clic en Save Draft.

3. Depure la herramienta en línea para verificar que la API sea invocable.

   Haga clic en Test Tool. Si habilitó la autenticación, introduzca la información de autenticación y los valores de los parámetros de entrada. Luego, haga clic en Start Running. Si la ejecución falla, ajuste la configuración basándose en el mensaje de error de la sección Run Result y vuelva a probar hasta que la ejecución sea exitosa. Puede introducir los valores de los parámetros de entrada manualmente o como código. Para parámetros complejos, utilice Edición de código. En el editor de código, puede enviar los parámetros de entrada completos en formato JSON y sus valores correspondientes.

4. Después de que la prueba sea exitosa, haga clic en Publish. Las aplicaciones solo pueden invocar herramientas que estén Publicadas.

Consola

• Method 1: Publique el complemento como un servicio MCP y luego agregue el servicio a una aplicación de agente.

  Step 1: Publish the plugin as an MCP service

  1. En la página Plugins, pase el cursor sobre la tarjeta del complemento objetivo y haga clic en Publish as MCP Service.

     Si el complemento ya se ha convertido en un servicio MCP, el botón cambia a Ver servicio MCP. Haga clic en él para ir a la página de Gestión de MCP y ver los detalles del servicio.

  2. Tras una publicación exitosa, puede ver los detalles del servicio MCP en la página Gestión de MCP, incluido el nombre del servicio, la descripción y el ID.

  Step 2: Add the MCP service to an agent application

  1. Vaya al lienzo de orquestación de la aplicación Aplicación de agente. En el bloque MCP, haga clic en +.

  2. En el panel Seleccionar servicio MCP, cambie a la pestaña Custom MCPS, busque el servicio MCP convertido desde el complemento y haga clic en Add All para agregarlo a la aplicación.

     También puede hacer clic en Convert from Plugin to MCP para publicar directamente un complemento que aún no se ha convertido.

  3. Pruebe si el complemento funciona como se espera.

     • Sin autenticación: Chatee con el modelo en el cuadro de entrada para probar la funcionalidad del complemento.
     • user-level authentication o service-level authentication: Antes de iniciar una conversación, haga clic en para configurar el token de autenticación. Solo necesita configurar el token una vez por sesión en esta página.
     • Si el Método de paso para un parámetro de entrada de una herramienta está establecido en Business Pass-through, debe hacer clic en para configurar el valor de la variable antes de iniciar una conversación. Solo necesita introducir el valor una vez por sesión en esta página.

  4. Después de completar la prueba, Publish la aplicación.

• Método 2: En la página Gestión de aplicaciones, vaya al lienzo de orquestación de su aplicación Aplicación de agente, agregue el servicio MCP desde el bloque MCP, pruebe su funcionalidad y luego Publique la aplicación.

API

El ID de herramienta identifica una herramienta específica. Cuando invoca una herramienta a través de una API, debe pasar el ID de herramienta correcto para garantizar que el sistema identifique correctamente la solicitud.

1. En la lista Plugins, busque el complemento que contiene la herramienta y haga clic en View Details.
2. Pase el puntero sobre el icono junto al nombre de la herramienta.
3. Haga clic en el icono para copiar el ID de la herramienta.

• Cuando invoca una aplicación mediante una API, si el complemento de la aplicación utiliza parámetros de business pass-through o requiere Autenticación a nivel de usuario, debe utilizar el parámetro biz_params para pasar la información de autenticación o la información de parámetros de transferencia directa. Para más información, consulte Referencia de la API de DashScope para flujos de trabajo y aplicaciones de agente heredadas.