Esta guía abarca la creación, gestión y uso de credenciales de IA (secretos compartidos) en modelos de lenguaje grandes (LLM), modelos de incrustación y herramientas de IA personalizadas en el complemento Discourse AI.
Nivel de usuario requerido: Administrador
Resumen
Las credenciales de IA ofrecen una forma centralizada y segura de gestionar secretos de autenticación, como claves de API, en toda la configuración de Discourse AI. En lugar de pegar claves de API sin procesar en cada modelo LLM, definición de incrustación o herramienta personalizada individualmente, puedes crear una credencial una sola vez y referenciarla donde sea necesario.
Cuando rotas una clave (por ejemplo, tu clave de API de OpenAI), la actualizas en un solo lugar y cada LLM, incrustación o herramienta que utilice la credencial detectará el cambio automáticamente.
Esta documentación cubre:
- Creación y gestión de credenciales
- Vinculación de credenciales a modelos LLM y de incrustación
- Uso de credenciales en herramientas de IA personalizadas
- Protección contra eliminación y ciclo de vida de las credenciales
- La API para gestionar credenciales programáticamente
¿Qué es una credencial?
Una credencial es un secreto con nombre y reutilizable almacenado centralmente en Discourse AI. Tiene dos campos principales:
| Campo | Descripción |
|---|---|
| Nombre | Una etiqueta única y legible por humanos (por ejemplo, “Clave de API de OpenAI”). Máximo 100 caracteres. |
| Valor | El secreto real (clave de API, token, etc.). Máximo 10.000 caracteres. |
Una credencial puede ser referenciada por tres tipos de entidades:
- Modelos LLM — como la clave de API principal
- Definiciones de incrustación — como la clave de API principal
- Herramientas de IA personalizadas — como vinculaciones de secretos con nombre accesibles desde JavaScript
Además, ciertos parámetros de proveedor de LLM del tipo “secreto” (por ejemplo, access_key_id para AWS Bedrock) también hacen referencia a credenciales.
Creación y gestión de credenciales
Acceder a la página de credenciales
Navega a Admin → Complementos → Discourse AI → Credenciales, o visita directamente /admin/plugins/discourse-ai/ai-secrets.
[marcador de posición de captura de pantalla: página de lista de credenciales mostrando las columnas de nombre, utilizado por y botón de editar]
Crear una nueva credencial
- En la página de credenciales, haz clic en “Nueva credencial”.
- Ingresa un Nombre para la credencial (por ejemplo, “Clave de API de OpenAI”).
- Ingresa el Valor — la clave de API o token real. Este campo se muestra como una entrada de contraseña.
- Haz clic en “Guardar”.
[marcador de posición de captura de pantalla: formulario de editor de credenciales con campos de nombre y valor]
También puedes crear credenciales en línea mientras configuras un LLM, una incrustación o una herramienta. Un cuadro de diálogo modal te permite agregar una nueva credencial sin salir de la página actual, y la credencial aparece inmediatamente en el menú desplegable de selección.
Editar una credencial
- En la página de lista de credenciales, haz clic en “Editar” junto a la credencial.
- Actualiza el Nombre o el Valor según sea necesario.
- Haz clic en “Guardar”.
Al ver una credencial existente, el valor del secreto está enmascarado (********) en la vista de lista. El valor real solo se muestra en la página de edición de la credencial individual.
Eliminar una credencial
Una credencial no se puede eliminar si está siendo referenciada actualmente por algún LLM, incrustación o herramienta. Si intentas eliminar una credencial que está en uso, la interfaz muestra un mensaje que enumera las entidades que la referencian, con enlaces a sus páginas de edición.
Para eliminar una credencial:
- Primero, elimina o reasigna todas las referencias a la credencial desde cualquier LLM, incrustación o herramienta.
- Vuelve a la página de edición de la credencial.
- Haz clic en “Eliminar” y confirma la acción.
Vinculación de credenciales a LLM e incrustaciones
Modelos LLM
Al configurar un modelo LLM en la página de configuración de LLM, puedes seleccionar una credencial existente desde un menú desplegable en lugar de pegar una clave de API directamente. En tiempo de ejecución, el modelo resuelve el secreto desde la credencial vinculada.
Para secretos específicos del proveedor, como el access_key_id de AWS Bedrock, el ID de la credencial se almacena dentro de los parámetros del proveedor y se resuelve de forma transparente cuando el modelo realiza solicitudes de API.
Definiciones de incrustación
Los modelos de incrustación funcionan de la misma manera. Al configurar una definición de incrustación, selecciona una credencial desde el menú desplegable. El modelo de incrustación valida que exista una credencial o una clave de API en línea y utiliza el valor de la credencial en tiempo de ejecución.
Uso de credenciales en herramientas de IA personalizadas
Las herramientas de IA personalizadas personalizadas utilizan un patrón de contrato y vinculación para los secretos, lo que mantiene la definición de la herramienta portátil (exportable/importable) mientras los secretos permanecen locales al sitio.
Paso 1: Declarar contratos de secretos
Al crear o editar una herramienta, declaras qué secretos requiere la herramienta agregando entradas a sus contratos de credenciales. Cada entrada tiene un alias — un identificador simple que usa letras, números y guiones bajos.
En la página del editor de herramientas, haz clic en “Agregar credencial” para agregar una nueva entrada de contrato y darle un nombre de alias, por ejemplo external_api_key.
[marcador de posición de captura de pantalla: editor de herramientas mostrando campos de alias de credencial y selectores de credenciales]
Los nombres de alias deben coincidir con el patrón [a-zA-Z0-9_] y ser únicos dentro de la herramienta.
Paso 2: Vincular credenciales a alias
Junto a cada alias declarado en la página de configuración de la herramienta, selecciona una credencial existente desde el menú desplegable. Esto crea una vinculación entre el alias y la credencial.
La vinculación se valida para asegurar:
- Que la credencial seleccionada existe
- Que el alias está declarado en los contratos de la herramienta
Paso 3: Acceder a secretos en tiempo de ejecución en JavaScript
Dentro del JavaScript de una herramienta, accede a los secretos usando la API secrets.get():
function invoke(params) {
const apiKey = secrets.get("external_api_key");
const result = http.get("https://api.example.com/data", {
headers: { "Authorization": "Bearer " + apiKey }
});
return JSON.parse(result.body);
}
Reemplaza external_api_key con el nombre del alias que declaraste en los contratos de credenciales de la herramienta.
Todos los alias declarados deben tener vinculaciones de credenciales antes de que la herramienta pueda ejecutarse. Si faltan algunas vinculaciones, la ejecución se bloquea con un mensaje de error que enumera los alias no vinculados.
Ejemplo: una herramienta con múltiples credenciales
Supongamos que estás creando una herramienta que llama a dos APIs diferentes. Declara dos contratos de credenciales:
| Alias | Descripción |
|---|---|
weather_api_key |
Clave para la API de datos meteorológicos |
geocode_api_key |
Clave para la API de geocodificación |
Luego, vincula cada alias a la credencial apropiada en la página de configuración de la herramienta.
En el script:
function invoke(params) {
const weatherKey = secrets.get("weather_api_key");
const geocodeKey = secrets.get("geocode_api_key");
const location = http.get(
"https://geocode.example.com/search?q=" + encodeURIComponent(params.city),
{ headers: { "X-Api-Key": geocodeKey } }
);
const coords = JSON.parse(location.body);
const forecast = http.get(
"https://weather.example.com/forecast?lat=" + coords.lat + "&lon=" + coords.lon,
{ headers: { "Authorization": "Bearer " + weatherKey } }
);
return JSON.parse(forecast.body);
}
Seguimiento del uso de credenciales
Cada credencial rastrea dónde se referencia. En la página de lista de credenciales, la columna “Utilizado por” muestra enlaces a cada LLM, incrustación o herramienta que actualmente usa esa credencial.
Esta visibilidad te ayuda a:
- Comprender el impacto antes de rotar o actualizar un secreto
- Identificar credenciales no utilizadas que se pueden eliminar de forma segura
- Navegar rápidamente a las entidades que dependen de una credencial
Referencia de API
Todos los puntos de conexión requieren autenticación de administrador y están bajo la ruta /admin/plugins/discourse-ai/ai-secrets.
| Método | Ruta | Descripción |
|---|---|---|
GET |
/ai-secrets |
Listar todas las credenciales (valores enmascarados) |
GET |
/ai-secrets/:id |
Mostrar una sola credencial (valor desenmascarado) |
POST |
/ai-secrets |
Crear una nueva credencial |
PUT |
/ai-secrets/:id |
Actualizar una credencial |
DELETE |
/ai-secrets/:id |
Eliminar una credencial (devuelve 409 si está en uso) |
Cuerpo de la solicitud para crear y actualizar:
{
"ai_secret": {
"name": "Clave de API de OpenAI",
"secret": "sk-..."
}
}
Todas las operaciones de creación, actualización y eliminación se registran en el registro de acciones del personal. Los valores de los secretos se tratan como sensibles y nunca se escriben en los registros.
Migración automática desde claves de API en línea
Las instalaciones existentes que anteriormente usaban claves de API en línea se migran automáticamente. La migración:
- Lee todos los modelos LLM y definiciones de incrustación no sembrados que tienen una clave de API en línea.
- Deduplica por clave de API y proveedor: si dos modelos comparten la misma clave y proveedor, reciben una sola credencial.
- Crea registros de credenciales con nombres generados automáticamente como “Clave de API de OpenAI”, “Clave de API de AWS Bedrock”, etc.
- Actualiza los registros de modelos LLM y definiciones de incrustación para que referencien las nuevas credenciales.
- Maneja los valores
access_key_idde AWS Bedrock en los parámetros del proveedor: extrae la clave sin procesar, crea una credencial y reemplaza el valor en línea con el ID de la credencial.
Esta migración se ejecuta automáticamente al actualizar y es irreversible. No se requiere ninguna acción manual.
Problemas comunes y soluciones
“Esta credencial está actualmente en uso y no se puede eliminar”
Esto significa que uno o más LLM, incrustaciones o herramientas referencian la credencial. Verifica la columna “Utilizado por” en la página de lista de credenciales para identificar y reasignar o eliminar esas referencias antes de eliminar.
“Faltan vinculaciones de credenciales requeridas” al ejecutar una herramienta
Todos los alias de credenciales declarados en los contratos de una herramienta deben tener vinculaciones. Abre la página de edición de la herramienta, verifica que cada alias tenga una credencial seleccionada en el menú desplegable y guarda.
El valor de la credencial se muestra como ********
Este es un comportamiento esperado. Los valores de los secretos están enmascarados en las vistas de lista por seguridad. Para ver o editar el valor real, haz clic en “Editar” en la credencial específica.
Roté una clave pero las funciones de IA siguen fallando
Después de actualizar el valor de una credencial, verifica que la prueba de LLM (en la página de configuración de LLM) se ejecute correctamente. Si la nueva clave tiene permisos diferentes o pertenece a una cuenta diferente, verifica los requisitos de configuración del proveedor.
Preguntas frecuentes
¿Puedo seguir usando claves de API en línea en lugar de credenciales?
Las claves de API en línea heredadas continúan funcionando para configuraciones existentes. Sin embargo, las credenciales son el enfoque recomendado porque simplifican la rotación de claves y reducen la duplicación.
¿Los valores de las credenciales están encriptados en reposo?
Los valores de las credenciales se almacenan en la base de datos. Siguen el mismo modelo de seguridad que otros datos sensibles de Discourse. Asegúrate de que tu base de datos esté adecuadamente protegida y que las copias de seguridad se manejen de manera apropiada.
¿Qué sucede cuando importo una herramienta que usa credenciales?
Las importaciones de herramientas incluyen los alias de contrato de credenciales pero no los valores reales de los secretos. Después de importar una herramienta, necesitarás crear o seleccionar credenciales para cada alias declarado en la página de configuración de la herramienta.
¿Puedo compartir una sola credencial entre múltiples LLM?
Sí. Múltiples LLM e incrustaciones pueden referenciar la misma credencial. Esto es particularmente útil cuando usas la misma clave de API de proveedor en varias configuraciones de modelos.