Iniciar sesiónReservar sesión

Capítulo 2.14

Proveedores y modelos de IA

Cómo el Enrutador de Proveedores de inteligencia artificial (IA) elige un modelo del propio conjunto de claves de la organización, y cómo los scripts y las herramientas de IA se comunican con Nexus desde el exterior.

Esta página fue traducida por IA a partir del original en inglés. Si algo no está claro, la página en inglés es la referencia. Leer esta página en inglés

16 minutos de lectura

Harrow Port Authority opera dos instalaciones. La que está en su red de operaciones aislada (capítulo 2.10, Instalación aislada) no cuenta con ningún proveedor alojado. En la instalación corporativa conectada, que es la que sigue este capítulo, la mayoría de las preguntas las responde un modelo que se ejecuta en dos nodos de unidad de procesamiento gráfico (GPU) en la propia sala de servidores del puerto. Una clave de Google Gemini, pagada por Harrow, asume el excedente cuando el modelo local está ocupado, y Aoife Brennan ha restringido el tráfico de inteligencia artificial (IA) de la organización a la UE. Nadie en Harrow configuró un modelo dentro de un servicio o de un complemento. Le indicaron a un componente lo que Harrow posee, y ese componente decide cada llamada.

Este capítulo aborda ese componente, el Enrutador de Proveedores de IA, al que la Parte 1 y la consola llaman la centralita de IA, y el fondo de claves del que se nutre. Termina con las formas en que los scripts y las herramientas de IA acceden a Nexus desde el exterior: claves para scripts, la interfaz de programación de aplicaciones (API) de transferencia de estado representacional (REST) y el Protocolo de Contexto de Modelo (MCP).

El Enrutador de Proveedores de IA

El enrutador se ejecuta dentro de la pasarela, nexus-gateway. Es el único servicio que guarda las credenciales de modelos de una organización y toma la decisión final sobre qué proveedor y qué modelo responden a cada solicitud. Todas las demás partes de Nexus se lo solicitan. Un paso del flujo de trabajo indica lo que desearía y el enrutador decide.

Solo unos pocos servicios pueden realizar solicitudes, y cada lista está fijada por el chart:

Qué se solicita Quién puede solicitarlo
Una finalización (/internal/ai/chat y su flujo continuo) nexus-orchestrator, nexus-workflows, nexus-skills-engine
Llamadas a herramientas y las demás rutas internas de IA nexus-orchestrator, nexus-workflows
Incrustaciones y reclasificación nexus-graphrag, nexus-skills-engine, nexus-workflows

Cada ruta interna comprueba dos elementos por turno: la clave de servicio interna del llamante y la identidad del llamante frente a la lista anterior. Una solicitud sin la clave se rechaza con MISSING_SERVICE_KEY (401), una clave incorrecta con INVALID_SERVICE_KEY (403), una solicitud que no indica quién llama con MISSING_CALLER_IDENTITY (403) y un llamante fuera de la lista con UNAUTHORIZED_CALLER (403). Ninguna de estas se reintenta, porque ninguna es un fallo pasajero.

Las aplicaciones y los complementos nunca aparecen en esa lista. Un complemento declara sus preferencias en las habilidades que registra y despacha a través de UNO, el motor de flujos de trabajo. A continuación, el orquestador realiza la solicitud al enrutador en nombre del complemento. Por este motivo, el secreto filtrado de un complemento puede actuar como dicho complemento, pero no puede gastar el presupuesto para modelos de nadie.

Izquierda: tres recuadros apilados, «Asistente», «Paso del flujo de trabajo», «Habilidad», cada uno con una flecha hacia un recuadro «Despacho de UNO (nexus-orchestrator)». Una flecha etiquetada «preferencias: proveedor preferido, modelo preferido, perfil de capacidades» va hacia la derecha hasta un recuadro grande «Enrutador de Proveedores de IA (nexus-gateway)». Dentro del recuadro del enrutador, tres recuadros pequeños en fila: «Rol», «Fondo de la organización», «Política de enrutamiento». Desde el enrutador, tres flechas van hacia la derecha hasta «Modelo local (ai.localProvider.baseUrl)», «Clave de proveedor alojado A», «Clave de proveedor alojado B». Debajo del enrutador, un recuadro separado «nexus-auth: el fondo de claves de la organización (cifrado)» con una flecha discontinua hacia arriba en dirección al enrutador etiquetada «claves, resueltas por llamada».
Cómo llega una solicitud a un modelo.

El conjunto de claves de la organización

Las claves de modelos pertenecen a la organización. Cada organización aporta su propia cuenta de proveedor y paga su propia factura, y la clave reside en el fondo de la organización, cifrada en nexus-auth. No existe una clave de plataforma compartida detrás de una organización, por lo que ninguna organización gasta jamás el presupuesto de otra. El coste de esa regla es evidente: una organización sin clave en su fondo no obtiene respuestas de IA. El asistente muestra MODEL_NOT_CONNECTED (503) e indica quién puede conectar una.

Se puede añadir una clave al fondo para cuatro proveedores:

Id. de proveedor Mostrado como
anthropic_api_key Anthropic
gemini Google Gemini
openrouter OpenRouter
scaleway Scaleway

Un servidor de modelos propio

Una organización también puede utilizar cualquier servidor que opere y que utilice la API compatible con OpenAI, como el modelo en los nodos GPU de Harrow. El instalador lo nombra en el archivo de valores:

# harrow-values.yaml (Helm values): the AI part
ai:
  localProvider:
    baseUrl: "https://models.harrow.example/v1"
  installationHosts:
    - models.harrow.example
    - 10.40.20.0/24
networkPolicy:
  externalEgressCIDRs:
    - 10.40.20.0/24

ai.localProvider.baseUrl apunta el adaptador compatible con OpenAI de la pasarela hacia su servidor. En una instalación, la ranura scaleway del fondo llega a ese servidor, de modo que la clave que usted añade para scaleway es la clave que espera su propio servidor.

ai.installationHosts enumera los nombres de host que están dentro de la instalación, además del propio dominio de servicio del despliegue y los tres hosts públicos. Cada entrada es un nombre de host, un .suffix, una dirección IP o un rango de enrutamiento entre dominios sin clases (CIDR) IPv4. El enrutador utiliza la lista para distinguir una llamada que permanece en las instalaciones de una que sale de ellas, que es lo que informa la comprobación «Nada sale de este sitio» en la página Conectar un modelo en su propio hardware.

La política de red importa tanto como el enrutador. El espacio de nombres deniega toda salida de forma predeterminada, por lo que la pasarela solo puede llegar a un servidor de modelos fuera del espacio de nombres cuando su rango está en networkPolicy.externalEgressCIDRs. Lo mismo ocurre con un proveedor alojado: si Harrow quiere que su clave de Gemini responda, los rangos de direcciones del proveedor también deben figurar allí, o la llamada nunca saldrá del clúster. El capítulo 2.16, Seguridad y redes, aborda la política en su totalidad.

Conectar un modelo en su propio hardware
Conectar un modelo en su propio hardware
Conexión de un modelo en su propio hardware. La página enumera los modelos que informa el servidor, el rol que desempeña cada uno y confirma que nada sale del sitio.

Añadir y retirar claves

Los propietarios y administradores de una organización gestionan su fondo. Ninguna otra persona puede ver las claves ni cambiarlas, y cualquier solicitud suya se rechaza con AUTHORITY_EXCEEDED.

En la consola

En Enterprise, el fondo se guarda en la centralita de IA, debajo de los motores. En Community, las mismas claves se guardan en Configuración, Modelos de IA. Esa página es el enrutador básico, donde usted añade claves y una dirección de modelo local y elige qué modelo realiza cada trabajo. Ambos muestran cada clave indicando quién la configuró y cuándo («Configurada por Aoife, 3 sept») y mediante una pista enmascarada de sus últimos cuatro caracteres como máximo, como ••••7f2q. La clave en sí no vuelve a mostrarse nunca después de añadirla.

La centralita de IA
La centralita de IA
La centralita de IA enumera cada proveedor indicando quién configuró su clave y qué trabajos realiza. Una clave está en reposo tras sufrir fallos, otra ha sido desactivada y la página indica adónde pueden ir los datos.
Modelos de IA
Modelos de IA
El enrutador básico en Community: una clave de organización, un modelo local en la propia máquina de la organización y qué modelo realiza cada trabajo.

A través de la API del BFF

El backend para frontend (BFF) de la consola sirve tres rutas para el fondo. Llámelas con el token de acceso propio de una persona: la organización procede del token, nunca de la solicitud.

GET  /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw

GET responde con los proveedores del fondo, si cada uno puede responder, cada clave por su pista y los proveedores para los que se puede añadir una clave. Añadir una clave requiere un cuerpo JSON con dos campos obligatorios y uno opcional:

{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }

La clave viaja una sola vez. nexus-auth la cifra y se lo comunica al enrutador, y la respuesta lleva únicamente la pista. La respuesta es 201 con el id de la nueva clave y su fila: «Añadida. La clave de Google Gemini ••••7f2q está en el fondo de IA de la organización, y el Enrutador de Proveedores de IA ya puede enrutar hacia ella». Una etiqueta tiene como máximo 100 caracteres, y una clave es una cadena sin espacios de como máximo 4,096 caracteres. Cualquier otro campo en el cuerpo, o un campo que nombre a una organización o a una persona, es rechazado.

La retirada requiere un cuerpo vacío. El enrutador deja de enrutar hacia la clave de inmediato, y nexus-auth la conserva, listada como retirada, para que su historial permanezca. Nunca se elimina nada en el fondo.

Rechazo HTTP Cuándo
VALIDATION_FAILED 400 Un cuerpo que no es {provider, api_key, label?}, un proveedor desconocido o la suscripción propia de una persona ofrecida como clave de organización
AUTHORITY_EXCEEDED 403 El llamante no es propietario ni administrador de la organización
RECORD_NOT_FOUND 404 No hay ninguna clave con ese id en el fondo de la organización
TRANSITION_NOT_PERMITTED 409 La clave ya está retirada
TENANT_NOT_A_PARAMETER 403 El cuerpo o la consulta nombró a una organización

Estados de las claves

Cada clave del fondo se encuentra en uno de seis estados. Solo una clave en uso responde a un chat.

Estado Qué significa
in_use La clave responde, hasta su fecha de caducidad si la tiene.
resting El enrutador la puso en reposo tras sufrir fallos, hasta una hora establecida. Mientras tanto, las solicitudes pasan a la siguiente clave.
exhausted Agotó su límite en el proveedor.
invalid El proveedor ya no la acepta.
expired Caducó en su fecha de vencimiento.
withdrawn Un administrador la retiró. Permanece listada como historial.

Una clave que falla permanece en reposo durante 60 segundos. Tras 5 fallos seguidos, el enrutador la desactiva, traslada su cuota a las demás claves y registra el aviso PROVIDER_KEY_SWITCHED_OFF. No se rechaza a nadie mientras otra clave pueda responder.

Cuando un proveedor no tiene ninguna clave en uso, el fondo indica el motivo («Ninguna clave en uso: 1 retirada, 1 caducada»). Cuando ningún proveedor del fondo tiene una clave en uso, el chat se rechaza con NO_PROVIDER_FOR_ROLE (422) y la solución: que un propietario o administrador añada una clave de organización. Ese es un estado de configuración y permanece en pantalla hasta que alguien lo solucione.

Roles, políticas y preferencias

El enrutador funciona por roles. Cada solicitud corresponde a uno de cinco: default, fast, reasoning, code o long_context. Cada modelo está también en un nivel, frontier, standard o fast, y se prefiere un nivel superior cuando el rol lo permite. La organización decide qué proveedor atiende cada rol (sus asignaciones de roles) y el orden de respaldo cuando un proveedor falla (su escalafón de política de enrutamiento). Los administradores configuran ambos en la centralita de IA. nexus-auth también los sirve en /auth/org/<organisation-id>/settings/ai-provider/role-assignments y /auth/org/<organisation-id>/settings/ai-provider/routing-policy para una clave de administrador que posea ai_provider:manage.

Los llamantes pueden indicar lo que desearían. Una fila de habilidad puede llevar un proveedor preferido y un modelo preferido, además de un perfil de capacidades. El enrutador trata cada uno de forma diferente:

  • Un proveedor preferido solo se respeta cuando la organización tiene ese proveedor habilitado y dispone de una clave para él. En caso contrario, el enrutador lo sustituye.
  • Un modelo preferido se respeta cuando está en el catálogo de ese proveedor y se ajusta al perfil.
  • Un perfil de capacidades es un filtro que nunca selecciona. Puede solicitar una ventana de contexto mínima, uso de herramientas, visión, incrustaciones, contexto largo o una residencia de datos. Cualquier opción que no lo cumpla no es apta.

El enrutador elige en un orden fijo. Respeta la preferencia cuando puede, luego prueba con otro modelo del mismo proveedor, después con la asignación de rol y con cualquier otro proveedor con clave cuyo catálogo se ajuste. Si se proporcionó un perfil y ningún catálogo se ajusta a él, la solicitud se rechaza con MODEL_CAPABILITY_UNAVAILABLE (422). Si no hay nada asignado y nada coincide, devuelve NO_PROVIDER_FOR_ROLE (422). No existe un modelo predeterminado de último recurso. Un rol que usted no haya configurado falla de forma explícita, con las propias palabras del enrutador indicando qué configurar.

La residencia de datos es la única restricción que no admite sustitución. Un perfil con eu_only es atendido por un proveedor de la UE o rechazado. Harrow establece este bloqueo para toda la organización, y la centralita muestra como desactivado el segundo proveedor alojado, que se encuentra en una región de EE. UU.

Una habilidad también puede fijar un modelo exacto cuando necesita ese modelo para funcionar. Incluso entonces, el enrutador utiliza la clave propia de la organización para dicho modelo y, sin ella, nada responde. Un llamante nunca puede hacer que Nexus utilice un proveedor que la organización no haya configurado.

Una vez elegido un proveedor, la conmutación por error es una cuestión aparte. Un error 429, 5xx o un fallo de red desplaza la solicitud por el escalafón hasta el siguiente proveedor. Un error 400, 401, 403 o 404 detiene el proceso de inmediato, porque las credenciales y las estructuras de solicitud no se transfieren entre proveedores y un reintento consumiría cuota para llegar al mismo fallo.

Para ver qué elegiría el enrutador antes de que alguien formule una pregunta, consulte GET /api/ai/routing-policy/effective en la pasarela con el token propio de una persona. Responde indicando el modelo para la organización con sesión iniciada, o el rechazo del enrutador expresado con palabras cuando no hay ninguno, y no envía ninguna solicitud a un modelo.

Supervisar el enrutador

La franja de cifras en la parte inferior de cada página muestra el modelo en uso («Modelo: local»). En Enterprise, La centralita de IA, en vivo traza el tráfico del enrutador a medida que ocurre: las solicitudes del asistente, los trabajos y las aplicaciones fluyendo a través de los roles hacia los proveedores y las claves, una clave en su reposo de 60 segundos trazada en gris, una clave desactivada trazada en rojo y un respaldo hacia el proveedor alojado cuando el modelo local está ocupado. Junto al flujo, grafica la carga por proveedor, las solicitudes por segundo y el tiempo de espera. Tomás la mantiene abierta durante la primera semana tras cualquier cambio en la política de enrutamiento, porque una asignación de rol incorrecta aparece allí en cuestión de minutos como tráfico dirigiéndose a un lugar que nadie pretendía.

En Community, la página Modelos de IA cuenta con el botón Probar todos los modelos, que comprueba cada modelo configurado y marca si responde. Es la forma más rápida de demostrar que una clave nueva funciona antes de que alguien dependa de ella.

La centralita de IA, en vivo
La centralita de IA, en vivo
El enrutador en vivo. El tráfico fluye desde el asistente y los trabajos a través de los roles hacia un modelo local y claves alojadas; una clave está en reposo, otra está desactivada y los puntos dorados muestran un respaldo mientras el modelo local está ocupado.

Embeddings

La búsqueda y el grafo de conocimiento convierten el texto en vectores. De forma predeterminada, la instalación realiza esto con un modelo de incrustación que se ejecuta dentro del clúster en el procesador, de modo que ningún texto sale del sitio para ser incrustado y una organización no necesita ninguna clave para ello. Utilizar un proveedor alojado para las incrustaciones es una elección que toma la organización; en ese caso, pasa por el mismo fondo y las mismas reglas.

Solo tres servicios pueden solicitar al enrutador incrustaciones o reclasificación: nexus-graphrag, nexus-skills-engine y nexus-workflows. GraphRAG realiza las incrustaciones en nombre de la organización a la que pertenece el contenido, con la configuración de dicha organización, y no posee ninguna clave de proveedor propia. Cuando una organización cambia su modelo de incrustación, nexus-workflows ejecuta el trabajo de reincrustación para los almacenes de esa organización.

Las credenciales de cada persona siguen siendo personales

Algunas credenciales pertenecen a una sola persona. El caso habitual es una suscripción a Claude Max, con sesión iniciada a través de la cuenta propia de esa persona. Una credencial así nunca es una clave de organización: el fondo la rechaza con VALIDATION_FAILED, nunca se incluye en la tabla de claves de la organización y ninguna pantalla de otra persona la muestra.

Las claves de modelos tampoco van nunca a ningún otro lugar. La página Claves de datos externos, que guarda claves para fuentes de datos externas, rechaza cualquier elemento que parezca una clave de modelo de IA con AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Si el lector de archivos encuentra claves de modelos dentro de un documento o configuración donde no deben estar, registra CREDENTIALS_IN_WRONG_PLACE y un administrador las elimina y las sustituye.

Scripts, REST y MCP

Nexus tiene tres hosts públicos. En Harrow son console.harrow.example para la consola, api.harrow.example para la pasarela y auth.harrow.example para el inicio de sesión. Los scripts y las herramientas utilizan el segundo y el tercero.

Claves para scripts

Un script inicia sesión con una clave creada en Configuración, Claves para scripts. Cada clave tiene un nombre, un alcance (por ejemplo, «Iniciar solo recuento de patio con drones»), la persona que la creó y una fecha de finalización; una organización puede fijar la duración máxima que puede tener una clave. El secreto se muestra una sola vez cuando se crea la clave. Cópielo en el almacén de secretos del script, porque Nexus conserva únicamente sus últimos cuatro caracteres. Una clave se retira, nunca se elimina: se detiene de inmediato y permanece listada con cada llamada que realizó. La rotación asigna a la clave un nuevo secreto y lo muestra una sola vez.

Cada clave tiene su propia página con llamadas por día, llamadas por servicio y un registro de actividad con hora, dirección, servicio y resultado. Una llamada fuera del alcance de la clave se rechaza y aparece en el registro.

nexus-auth sirve las mismas claves a una persona con sesión iniciada en https://auth.harrow.example/api-keys: crear y listar, y luego leer, cambiar, revocar o rotar una clave por su id.

Una clave para scripts
Una clave para scripts
Una clave para scripts. La página muestra el alcance de la clave, quién la creó, su fecha de finalización, las llamadas por día y por servicio, y el resultado de cada llamada; el secreto termina en …7QK2 y no vuelve a mostrarse nunca.

REST a través de la pasarela

Envíe llamadas REST a https://api.harrow.example con Authorization: Bearer <token-or-key>. Cada clave debe pertenecer a una organización. Una clave sin organización es rechazada con TOKEN_ORG_MISSING (403) por todos los servicios que comprueban claves a través de nexus-auth.

A un llamante que realiza solicitudes con demasiada frecuencia se le responde 429 con RATE_LIMITED, un encabezado Retry-After y el límite y la ventana en el cuerpo. Espere el número de segundos que indique. En Enterprise, los administradores establecen límites por clave, por aplicación y por unidad en Configuración, Límites de tasa (véase el capítulo 2.16, Seguridad y redes).

MCP para herramientas de IA

Las herramientas de IA que utilizan el Protocolo de Contexto de Modelo se conectan a https://api.harrow.example/mcp. Inician sesión a través del servidor OAuth 2.1 (OAuth es el estándar abierto para autorización delegada) en https://auth.harrow.example, que admite el registro de clientes por parte de la propia herramienta, de modo que una herramienta como Claude Code o Cursor se registra a sí misma y abre el navegador de la persona para iniciar sesión. A partir de entonces, la conexión actúa en nombre de esa única persona, con los derechos de esa persona y nada más. Una persona con sesión iniciada puede obtener una configuración lista para usar para una herramienta de línea de comandos desde https://auth.harrow.example/api/v1/mcp/cli-config.

Las llamadas a herramientas que necesitan un modelo pasan por el enrutador como todo lo demás, bajo la organización de la persona.