Crear API de modelo personalizado

Descargar como PDF

Última actualización2025/07/07

La opción Crear un modelo API personalizado brinda a los desarrolladores y administradores la capacidad de integrar sin problemas modelos de lenguaje extenso (LLM) propios o de terceros y otros modelos de IA directamente en AI Agent Studio.

Requiere un esquema de carga útil JSON, que encapsula información sobre el modelo. El esquema define atributos como el nombre del proveedor, el nombre del modelo específico, los protocolos de autenticación, los detalles del endpoint de la API (incluidos parámetros de ruta, parámetros de consulta y encabezados requeridos), y la estructura de los cuerpos de solicitud y respuesta.
La API permite a los usuarios definir variables dentro de los cuerpos de solicitud y respuesta que pueden llenarse dinámicamente durante el tiempo de ejecución. Estas variables se pueden designar para diferentes propósitos a través de anotaciones específicas:
- PROMPT_QUERY (Obligatorio): Esta anotación significa que la variable correspondiente debe reemplazarse con el indicador proporcionado por el usuario en la página de AI Skills. Esto es esencial para pasar los indicadores de entrada del usuario al modelo.
- REQUEST_PARAMETER (Obligatorio): Esta anotación indica que la variable debe exponerse como un parámetro configurable en la página de Model connections.
- MODEL_PARAMETER : Similar a REQUEST_PARAMETER, esta anotación designa la variable para la configuración en la página de AI Skills.
- RESPONSE_PARAMETER (Obligatorio): Esta anotación significa que la variable será devuelta en la respuesta del modelo de IA.
La API devuelve una respuesta 200 OK con el modelo creado al completarse la creación con éxito.

POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel

Cuerpo de la solicitud:

{
   "name":"Azure OpenAI reasoning models",
   "version":"0",
   "authAction":{
      "authType":"CUSTOM_KEYS",
      "customKeys":{
         "keys":[
            {
               "location":"header",
               "keyName":"Authorization",
               "prefix":"Bearer "
            }
         ]
      }
   },
   "apiType":"REST",
   "actions":[
      {
         "name":"o3-mini",
         "displayName":"o3-mini",
         "description":"The o1 and o3 series models are specifically designed to tackle reasoning 
          and problem-solving tasks with increased focus and capability. These models spend more time 
          processing and understanding the user's request, making them exceptionally strong in areas 
          like science, coding, math and similar fields. For example, o1 can be used by healthcare researchers 
          to annotate cell sequencing data, by physicists to generate complicated mathematical formulas needed 
          for quantum optics, and by developers in all fields to build and execute multi-step workflows.",
         "method":"POST",
         "uri":"https://{deployment}.openai.azure.com/openai/deployments/o3-mini/chat/completions?api-version=2025-01-01-preview",
         "params":[
            {
               "type":"HEADERS"
            },
            {
               "type":"PATH_PARAM",
               "attribute":[
                  {
                     "name":"deployment",
                     "label":"Deployment",
                     "value":{
                        "type":"TEXT",
                        "string":"aai-openai2"
                     }
                  }
               ]
            }
         ],
         "request":{
            "raw":{
               "body":"{\n        \"messages\": [\n            {\n                \"role\": \"user\",
                \n                \"content\": \"I am going to       Paris, what should I see?\"\n            
                 }\n        ],\n        \"max_completion_tokens\": 100000,\n        \"model\": \"o3-mini\"\n    }",
               "variables":[
                  {
                     "path":"$.max_completion_tokens",
                     "attribute":{
                        "name":"max_completion_tokens",
                        "label":"max_completion_tokens",
                        "value":{
                           "type":"INTEGER",
                           "number":"100000"
                        },
                        "annotations":[
                           "REQUEST_PARAMETER"
                        ]
                     }
                  },
                  {
                     "path":"$.messages.content",
                     "attribute":{
                        "name":"prompt",
                        "label":"prompt",
                        "value":{
                           "type":"TEXT"
                        },
                        "annotations":[
                           "PROMPT_QUERY"
                        ]
                     }
                  }
               ]
            }
         },
         "response":{
            "body":"{\n    \"id\": \"chatcmpl-APwQdLa9WCQAdZg0dO5OjGr2ER4sX\",\n    \"object\": \"chat.completion\",\n
                   \"created\": 1730746163,\n    \"model\": \"o3-mini-2025-01-31\",\n    \"choices\": [\n        {\n
                   \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                
                   \"content\": \"Sure! They are one of the most mysterious and exciting objects in space.\",\n
                   \"refusal\": null\n            },\n            \"finish_reason\": \"stop\"\n        }\n    ],\n
                   \"usage\": {\n                \"prompt_tokens\": 17,\n        \"completion_tokens\": 959,\n
                   \"total_tokens\": 976,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0\n
                    },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 64\n        }\n
                    },\n    \"system_fingerprint\": \"fp_35c19d48ca\"\n}",
            "variables":[
               {
                  "path":"$.usage.completion_tokens",
                  "attribute":{
                     "name":"completion_tokens",
                     "label":"completion_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].completionTokens"
                  }
               },
               {
                  "path":"$.choices.message.content",
                  "attribute":{
                     "name":"content",
                     "label":"content",
                     "value":{
                        "type":"TEXT",
                        "string":"Some response from LLM"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].value"
                  }
               },
               {
                  "path":"$.model",
                  "attribute":{
                     "name":"model",
                     "label":"model",
                     "value":{
                        "type":"TEXT"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"model_name"
                  }
               },
               {
                  "path":"$.usage.prompt_tokens",
                  "attribute":{
                     "name":"prompt_tokens",
                     "label":"prompt_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].promptTokens"
                  }
               },
               {
                  "path":"$.usage.total_tokens",
                  "attribute":{
                     "name":"total_tokens",
                     "label":"total_tokens",
                     "value":{
                        "type":"INTEGER"
                     },
                     "annotations":[
                        "RESPONSE_PARAMETER"
                     ],
                     "canonicalName":"choices[0].totalTokens"
                  }
               }
            ]
         }
      }
   ]
}

Parámetros de solicitud


Parámetro	Tipo	Obligatorio	Descripción
nombre	String	Sí	Nombre del modelo personalizado
Descripción	String	No	Descripción del modelo personalizado
authAction	Objeto	Sí	Define las opciones de autenticación para la llamada al modelo de IA. Consulte a continuación para obtener más detalles
apiType	String	Sí	Especifica el tipo de API (p. ej., "REST")
acciones	Matriz	Sí	Contiene una matriz de objetos, donde cada objeto define un punto final de modelo específico o una acción dentro del modelo personalizado.

Objeto `authAction`

{
   "name":"Azure OpenAI reasoning models",
   "description":"string",
   "version":"0",
   "authAction":{
      "authType":"CUSTOM_KEYS",
      "customKeys":{
         "keys":[
            {
               "location":"header",
               "keyName":"Authorization",
               "prefix":"Bearer "
            }
         ]
      }
   }


{
   "name":"Bedrock - Claude2.1",
   "description":"string",
   "version":"string",
   "authAction":{
      "authType":"AWS_SIGNATURE_V4",
      "awsSignatureV4":{
         "accessKey":{
            "location":"header",
            "keyName":"aws_sign_access_key"
         },
         "secretkey":{
            "location":"header",
            "keyName":"aws_sign_access_key"
         },
         "sessionkey":{
            "location":"header",
            "keyName":"aws_sign_session_key"
         }
      }
   },
   "api_type":"REST",
   "actions":[
      {
         .... 
      }
   ]
}


Parámetro	Tipo	Obligatorio	Descripción
authType	Cadena	Sí	Tipo de autenticación. `API_KEY` para la clave de API, `OAUTH2` para OAuth2, `CUSTOM_KEYS` para varias claves y `AWS_SIGNATURE_V4` para la autenticación específica de AWS.
API_KEY, OAUTH2 o CUSTOM_KEYS	Objeto	Sí	Define las claves de autenticación personalizadas. Sus atributos se describen a continuación en la sección de `claves`. `API_KEY` es obligatorio, si `authType` es `API_KEY`. `OAUTH2` es obligatorio, si `authType` es `OAUTH2`. `CUSTOM_KEYS` es obligatorio, si `authType` es `CUSTOM_KEYS`.
↳↳ `claves`	Matriz	Sí	Una matriz de objetos clave para la autenticación.
↳↳↳ `ubicación`	Cadena	Sí	Dónde se debe colocar la clave (p. ej., “encabezado”).
↳↳↳`keyName`	Cadena	Sí	El nombre de la clave (p. ej., “Autorización”, “x-api-key”).
↳↳↳ `prefijo`	Objeto	No	Prefijo opcional que se añade al valor de la clave (p. ej., “Portador” para los tokens de portador).
awsSignatureV4	Objeto	Sí	`AWS_SIGNATURE_V4` es obligatorio si `authType` es `AWS_SIGNATURE_V4`. Este objeto define las credenciales de AWS (ID de clave de acceso, clave de acceso secreta, clave de sesión) para la autenticación de firma de AWS.
↳↳ `accessKey`	Objeto	Sí	Define el ID de la clave de acceso de AWS.
↳↳↳ `ubicación`	Cadena	Sí	Dónde se debe colocar la clave de acceso (p. ej., “encabezado”, “consulta”).
↳↳↳ `keyName`	Cadena	Sí	El nombre del parámetro para la clave de acceso (p. ej., “aws_sign_access_key”).
↳↳ `secretkey`	Objeto	Sí	Define la clave de acceso secreta de AWS.
↳↳↳ `ubicación`	Cadena	Sí	Dónde debe colocarse la clave secreta.
↳↳↳ `keyName`	Cadena	Sí	El nombre del parámetro para la clave secreta.
↳↳ `sessionkey`	Objeto	No	Define la clave de sesión de AWS (opcional).
↳↳↳ `ubicación`	Cadena	Sí	Dónde debe colocarse la clave de sesión.
↳↳↳ `keyName`	Cadena	Sí	El nombre del parámetro para la clave de sesión.

Matriz de `acciones`

{
   "actions":[
      {
         "name":"o3-mini",
         "displayName":"o3-mini",
         "description":"The o1 and o3 series models are specifically designed to tackle reasoning 
          and problem-solving tasks with increased focus and capability. These models spend more time 
          processing and understanding the user's request, making them exceptionally strong in areas 
          like science, coding, math and similar fields. For example, o1 can be used by healthcare researchers 
          to annotate cell sequencing data, by physicists to generate complicated mathematical formulas needed 
          for quantum optics, and by developers in all fields to build and execute multi-step workflows.",
         "method":"POST",
         "uri":"https://{deployment}.openai.azure.com/openai/deployments/o3-mini/chat/completions?api-version=2025-01-01-preview",
         "params":[
            {
               "type":"string",
               "attribute":[
                  {
                     "name":"string",
                     "label":"string",
                     "value":{
                        "type":"string",
                        "string":"string",
                        "number":"string"
                     }
                  }
               ]
            }
         ],
         "request":{
            "raw":{
               "body":"string",
               "variables":[
                  {
                     ....
                  }
               ]
            }
         },
         "response":{
            "body":"string",
            "variables":[
               {
                  ....
               }
            ]
         }
      }
   ]
}


Parámetro	Tipo	Obligatorio	Descripción
nombre	String	Sí	El nombre programático del punto final o la acción específicos del modelo.
displayName	Cadena	Sí	Un nombre fácil de usar para el punto final del modelo, que se muestra en la interfaz de usuario.
Descripción	String	No	Una descripción detallada del punto final del modelo y sus capacidades.
método	Cadena	Sí	El método HTTP para la solicitud API. Por lo general, debe ser `POST` para la mayoría de los modelos de IA generativa.
uri	Cadena	Sí	La URI completa del punto final del modelo de IA. Parámetros dinámicos en la URI.
parámetros	Matriz	No	Contiene una colección de parámetros que se utilizan al configurar la Model connection y se insertarán en el URI de destino al llamar a la API del modelo de IA en tiempo de ejecución. El parámetro puede ser una variable `PATH_PARAM` o una variable `QUERY_PARAM`. También puede agregar ENCABEZADOS que estén asociados con esta solicitud de API. En el ejemplo, `deploymentId` y `projectId` son una variable PATH_PARAM y `apiVersion` es una variable QUERY_PARAM.
Solicitud	Objeto	Sí	Define el formato y la estructura de los datos que se deben enviar al modelo, incluidas las variables y sus anotaciones. El `cuerpo` especifica la estructura y el contenido de la solicitud. La matriz de `variables` define los elementos dinámicos dentro del cuerpo, usando la ruta para especificar la ubicación de la variable en la estructura JSON.
Respuesta	Objeto		Especifica el formato y la estructura de los datos que el modelo devolverá, incluidas las variables, sus anotaciones y sus nombres canónicos. El `cuerpo` especifica la estructura y el contenido de la respuesta. La matriz de `variables` define los elementos dinámicos dentro del cuerpo, usando la ruta para especificar la ubicación de la variable en la estructura JSON.

Matriz de `parámetros`

{
   "params":[
      {
         "type":"HEADERS"
      },
      {
         "type":"PATH_PARAM",
         "attribute":[
            {
               "name":"deployment",
               "label":"Deployment",
               "value":{
                  "type":"TEXT",
                  "string":"aai-openai2"
               }
            }
         ]
      }
   ]


Parámetro	Tipo	Obligatorio	Descripción
tipo	Cadena	Sí	El tipo de parámetro (p. ej., `HEADERS`, `PATH_PARAM`, `QUERY_PARAM`).
atributo	Matriz	Sí	Una matriz de objetos de atributo que definen los detalles del parámetro. Requerido para `PATH_PARAM` y `QUERY_PARAM`.
↳ `nombre`	Cadena	Sí	El nombre del parámetro (p. ej., “implementación”, “api-version”).
↳ `etiqueta`	Cadena	No	Una etiqueta fácil de usar para el parámetro, que se muestra en la interfaz de usuario.
↳`valor`	Objeto	No	Un objeto que contiene el valor predeterminado o inicial del parámetro. A continuación, se presentan los atributos: `tipo` (string): El tipo de dato del valor del parámetro (p. ej., `TEXT`, `INTEGER`). `string` (string): El valor de string si el `tipo` es `TEXT`. `número` (string): El valor numérico si el `tipo` es `INTEGER`.

Objeto de `solicitud`

{
    "request":{
      "raw":{
         "body":"{\n        \"messages\": [\n            {\n                \"role\": \"user\",
                \n                \"content\": \"I am going to       Paris, what should I see?\"\n            
                 }\n        ],\n        \"max_completion_tokens\": 100000,\n        \"model\": \"o3-mini\"\n    }",
         "variables":[
            {
               "path":"$.max_completion_tokens",
               "attribute":{
                  "name":"max_completion_tokens",
                  "label":"max_completion_tokens",
                  "value":{
                     "type":"INTEGER",
                     "number":"100000"
                  },
                  "annotations":[
                     "REQUEST_PARAMETER"
                  ]
               }
            },
            {
               "path":"$.messages.content",
               "attribute":{
                  "name":"prompt",
                  "label":"prompt",
                  "value":{
                     "type":"TEXT"
                  },
                  "annotations":[
                     "PROMPT_QUERY"
                  ]
               }
            }
         ]
      }
   }


Parámetro	Tipo	Obligatorio	Descripción
sin procesar	Objeto	Sí	Define el cuerpo de la solicitud sin procesar y sus variables dinámicas.
↳ `cuerpo`	Cadena	Sí	La string JSON sin procesar que representa la estructura del cuerpo de la solicitud. Esta string debe contener marcadores de posición para variables.
↳ `variables`	Matriz	No	Una matriz de objetos que define elementos dinámicos dentro del `cuerpo`.
↳↳ `ruta`	Cadena	Sí	La ruta JSONPath a la ubicación de la variable dentro de la estructura JSON del `cuerpo`.
↳↳ `atributo`	Objeto	Sí	Un objeto que describe las propiedades de la variable.
↳↳↳ `nombre`	Cadena	Sí	El nombre interno de la variable.
↳↳↳`etiqueta`	Cadena	No	Una etiqueta fácil de usar para la variable.
↳↳↳ `valor`	Objeto	No	Un objeto que contiene el valor predeterminado o inicial de la variable.
↳↳↳ `anotaciones`	Matriz	No	Una matriz de strings que especifica el propósito de la variable. Anotaciones compatibles: `PROMPT_QUERY`, `REQUEST_PARAMETER`, `MODEL_PARAMETER`.

Objeto de `respuesta`

{
      "response":{
      "body":"{\n    \"id\": \"chatcmpl-APwQdLa9WCQAdZg0dO5OjGr2ER4sX\",\n    \"object\": \"chat.completion\",\n
                   \"created\": 1730746163,\n    \"model\": \"o3-mini-2025-01-31\",\n    \"choices\": [\n        {\n
                   \"index\": 0,\n            \"message\": {\n                \"role\": \"assistant\",\n                
                   \"content\": \"Sure! They are one of the most mysterious and exciting objects in space.\",\n
                   \"refusal\": null\n            },\n            \"finish_reason\": \"stop\"\n        }\n    ],\n
                   \"usage\": {\n                \"prompt_tokens\": 17,\n        \"completion_tokens\": 959,\n
                   \"total_tokens\": 976,\n        \"prompt_tokens_details\": {\n            \"cached_tokens\": 0\n
                    },\n        \"completion_tokens_details\": {\n            \"reasoning_tokens\": 64\n        }\n
                    },\n    \"system_fingerprint\": \"fp_35c19d48ca\"\n}",
      "variables":[
         {
            "path":"$.usage.completion_tokens",
            "attribute":{
               "name":"completion_tokens",
               "label":"completion_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].completionTokens"
            }
         },
         {
            "path":"$.choices.message.content",
            "attribute":{
               "name":"content",
               "label":"content",
               "value":{
                  "type":"TEXT",
                  "string":"Some response from LLM"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].value"
            }
         },
         {
            "path":"$.model",
            "attribute":{
               "name":"model",
               "label":"model",
               "value":{
                  "type":"TEXT"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"model_name"
            }
         },
         {
            "path":"$.usage.prompt_tokens",
            "attribute":{
               "name":"prompt_tokens",
               "label":"prompt_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].promptTokens"
            }
         },
         {
            "path":"$.usage.total_tokens",
            "attribute":{
               "name":"total_tokens",
               "label":"total_tokens",
               "value":{
                  "type":"INTEGER"
               },
               "annotations":[
                  "RESPONSE_PARAMETER"
               ],
               "canonicalName":"choices[0].totalTokens"
            }
         }
      ]
   }
}


Parámetro	Tipo	Obligatorio	Descripción
cuerpo	Cadena	Sí	La string JSON sin procesar que representa la estructura esperada del cuerpo de respuesta del modelo.
variables	Matriz	No	Una matriz de objetos que define cómo extraer elementos dinámicos del `cuerpo` de la respuesta.
↳ `ruta`	Cadena	Sí	La ruta JSONPath a la ubicación de la variable dentro de la estructura JSON del `cuerpo`.
↳ `atributo`	Objeto	Sí	Un objeto que describe las propiedades de la variable.
↳↳ `nombre`	Cadena	Sí	El nombre interno de la variable.
↳↳`etiqueta`	Cadena	No	Una etiqueta fácil de usar para la variable.
↳↳ `valor`	Objeto	No	Un objeto que contiene el valor predeterminado o inicial de la variable.
↳↳ `anotaciones`	Matriz	No	Una matriz de strings que especifica el propósito de la variable. Anotación compatible: `RESPONSE_PARAMETER`.
↳↳ `canonicalName`	Cadena	No	Ruta JSON a la variable en el esquema canónico de Automation Anywhere. Use `choices[0].completionTokens` para completar el número de tokens consumidos al generar la respuesta. Use `choices[0].value` para completar la respuesta de LLM. Utilice `model_name` para completar el nombre o identificador del modelo de IA. Use `choices[0].promptTokens` para completar el número de tokens consumidos por el indicador. Use `choices[0].totalTokens` para completar el total de tokens consumidos para cumplir con la solicitud.

Para obtener más detalles de la API a fin de crear un modelo personalizado, incluidos la respuesta y los parámetros de respuesta, consulte API de AI Agent Studio

Otras API de modelos personalizados

Obtener API de información de modelo personalizado

GET https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}

Esta API recupera la definición de modelos personalizados existentes.
Requiere el nombre del proveedor (vendorName) y el nombre del modelo (modelName) como parámetros de ruta.
La API devuelve una respuesta 200 OK que contiene los objetos que representan el modelo solicitado.

Actualizar la API de definición de modelo personalizado

PUT https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel

Esta API actualiza una definición de modelo personalizado existente.
Nota: Esta API solo puede actualizar modelos personalizados que no tienen asociada ninguna Model connections.
Requiere el nombre del proveedor (vendorName) y el nombre del modelo (modelName) para identificar el modelo que se actualizará.
La API devuelve una respuesta 200 OK con el modelo actualizado cuando se actualiza con éxito.

Actualiza el nombre y la descripción de la API de definición de modelo personalizado

PATCH https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel

Esta API actualiza el nombre y la descripción de la definición del modelo personalizado.
Requiere el nombre del proveedor (vendorName) y el nombre del modelo (modelName) para identificar el modelo que se actualizará.
La API devuelve una respuesta 200 OK con los detalles del modelo actualizado cuando se actualiza con éxito.

Eliminar API de modelo personalizado

DELETE https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/vendors/{vendorName}/models/{modelName}

Esta API elimina un modelo personalizado existente.
Similar al API GET, utiliza (vendorName) y (modelName) como parámetros de ruta para identificar el modelo objetivo.
Nota: El modelo solo puede eliminarse si no está actualmente asociado con Model connections activas. Esto significa que primero debe eliminar cualquier AI Skills y Task Bots que dependan de la Model connection antes de intentar eliminar la definición del modelo.
La API devuelve una respuesta 204 No Content tras la eliminación exitosa.

API de lista de modelos personalizados

POST https:/{{ControlRoomURL}}/gai/prompttools/v1/custommodel/list

Esta API recupera una lista de todos los modelos personalizados definidos para todos los proveedores dentro de la Control Room.
Acepta un cuerpo de solicitud opcional que contiene un objeto FilterRequest, lo que permite a los usuarios filtrar los resultados según criterios específicos.
La API devuelve una respuesta 200 OK con objetos que contienen los modelos solicitados.

Para obtener más detalles sobre las API anteriores, consulte API de AI Agent Studio. Puede descargar aquí una colección de Postman para AI Agent Studio: definiciones de modelos personalizados que contienen ejemplos de llamadas a la API para conectarse a los modelos personalizados.