Versão 1.0.0-alpha.1mais recente
Capítulo 2.14
Fornecedores e modelos de IA
Como o encaminhador de fornecedores de inteligência artificial (IA) (AI Provider Router) seleciona um modelo do conjunto de chaves da própria organização e como scripts e ferramentas de IA acedem ao Nexus a partir do exterior.
Esta página foi traduzida por IA a partir do original em inglês. Em caso de dúvida, a página em inglês serve de referência. Ler esta página em inglês

A Harrow Port Authority mantém duas instalações. A da sua rede de operações isolada (air-gapped) (capítulo 2.10, Instalação isolada) não tem qualquer fornecedor alojado. Na instalação empresarial ligada, que este capítulo acompanha, a maioria das questões é respondida por um modelo em execução em dois nós de unidades de processamento gráfico (GPU) na própria sala de servidores do porto. Uma chave do Google Gemini, paga pela Harrow, assume o excedente quando o modelo local está ocupado, e Aoife Brennan bloqueou o tráfego de inteligência artificial (IA) da organização à UE. Ninguém na Harrow configurou um modelo dentro de um serviço ou de um plugin. Indicaram a um componente o que a Harrow possui, e esse componente decide cada chamada.
Este capítulo aborda esse componente, o AI Provider Router, a que a Parte 1 e a consola chamam central de comutação de IA, e o conjunto (pool) de chaves a que recorre. Termina com as formas como os scripts e as ferramentas de IA chegam ao Nexus a partir do exterior: chaves para scripts, a interface de programação de aplicações (API) de transferência de estado representacional (REST) e o Model Context Protocol (MCP).
O AI Provider Router
O encaminhador (router) corre dentro do gateway, nexus-gateway. É o único serviço que detém as credenciais de modelos de uma organização, e toma a decisão final sobre que fornecedor e que modelo respondem a cada pedido. Todas as outras partes do Nexus perguntam-lhe. Um passo do fluxo de trabalho indica o que gostaria, e o encaminhador decide.
Apenas alguns serviços podem pedir, e cada lista é fixada pelo chart:
| O que é pedido | Quem pode pedir |
|---|---|
Uma conclusão (/internal/ai/chat e a respetiva stream) |
nexus-orchestrator, nexus-workflows, nexus-skills-engine |
| Chamadas de ferramentas e as outras rotas internas de IA | nexus-orchestrator, nexus-workflows |
| Embeddings e reclassificação (reranking) | nexus-graphrag, nexus-skills-engine, nexus-workflows |
Cada rota interna verifica duas coisas sucessivamente: a chave de serviço interno do requerente e a identidade do requerente face à lista acima. Um pedido sem a chave é recusado com MISSING_SERVICE_KEY (401), uma chave errada com INVALID_SERVICE_KEY (403), um pedido que não diga quem está a chamar com MISSING_CALLER_IDENTITY (403) e um requerente fora da lista com UNAUTHORIZED_CALLER (403). Nenhum destes é tentado novamente, porque nenhum deles é uma falha passageira.
As aplicações e os plugins nunca aparecem nessa lista. Um plugin declara as suas preferências nas competências (skills) que regista e despacha através do UNO, o motor de fluxos de trabalho. O orquestrador pede então ao encaminhador em nome do plugin. É por isto que um segredo de plugin divulgado pode agir como esse plugin, mas não pode gastar o orçamento de modelos de ninguém.
O conjunto de chaves da organização
As chaves de modelos pertencem à organização. Cada organização traz a sua própria conta de fornecedor e paga a sua própria fatura, e a chave reside no conjunto (pool) da organização, encriptada no nexus-auth. Não existe uma chave de plataforma partilhada por trás de uma organização, pelo que nenhuma organização gasta alguma vez o orçamento de outra. O custo dessa regra é simples: uma organização sem chave no seu conjunto não obtém respostas de IA. O assistente mostra MODEL_NOT_CONNECTED (503) e indica quem pode ligar uma.
Uma chave pode ser adicionada ao conjunto para quatro fornecedores:
| ID do fornecedor | Mostrado como |
|---|---|
anthropic_api_key |
Anthropic |
gemini |
Google Gemini |
openrouter |
OpenRouter |
scaleway |
Scaleway |
Um servidor de modelos próprio
Uma organização também pode utilizar qualquer servidor que opere e que comunique através da API compatível com OpenAI, tal como o modelo nos nós de GPU da Harrow. O instalador nomeia-o no ficheiro 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/24ai.localProvider.baseUrl aponta o adaptador compatível com OpenAI do gateway para o seu servidor. Numa instalação, a ranhura (slot) scaleway do conjunto chega a esse servidor, pelo que a chave que adicionar para scaleway é a chave que o seu próprio servidor espera.
ai.installationHosts lista nomes de anfitrião (host names) que estão dentro da instalação, além do próprio domínio de serviço do lançamento e dos três anfitriões públicos. Cada entrada é um nome de anfitrião, um .suffix, um endereço IP ou um intervalo Classless Inter-Domain Routing (CIDR) IPv4. O encaminhador utiliza a lista para distinguir uma chamada que permanece nas instalações de uma que sai delas, que é o que a verificação "Nada sai destas instalações" na página Ligar um modelo no seu próprio hardware comunica.
A política de rede importa tanto como o encaminhador. O namespace nega todo o tráfego de saída (egress) por predefinição, pelo que o gateway só pode alcançar um servidor de modelos fora do namespace quando o seu intervalo está em networkPolicy.externalEgressCIDRs. O mesmo se aplica a um fornecedor alojado: se a Harrow quiser que a sua chave Gemini responda, os intervalos de endereços do fornecedor também têm de estar aí listados, ou a chamada nunca sai do cluster. O Capítulo 2.16, Segurança e redes, aborda a política na íntegra.
Adicionar e retirar chaves
Os proprietários e administradores de uma organização gerem o seu conjunto. Qualquer outra pessoa não pode ver as chaves nem alterá-las, e um pedido seu é recusado com AUTHORITY_EXCEEDED.
Na consola
Na versão Enterprise, o conjunto é mantido na central de comutação de IA, sob os motores. Na versão Community, as mesmas chaves são mantidas em Definições, Modelos de IA. Essa página é o encaminhador básico, onde adiciona chaves e um endereço de modelo local e escolhe que modelo faz que trabalho. Ambos mostram cada chave por quem a definiu e quando ("Definida por Aoife, 3 de set.") e por uma dica mascarada dos seus últimos quatro caracteres, no máximo, tal como ••••7f2q. A chave em si nunca mais é mostrada depois de a adicionar.
Através da API BFF
O backend for frontend (BFF) da consola serve três rotas para o conjunto. Chame-as com o próprio token de acesso de uma pessoa: a organização provém do token, nunca do pedido.
GET /api/v1/ai-providers
POST /api/v1/ai-providers/keys
POST /api/v1/ai-providers/keys/<key-id>/withdraw
GET responde com os fornecedores no conjunto, se cada um pode responder, cada chave pela sua dica e os fornecedores para os quais uma chave pode ser adicionada. Adicionar uma chave requer um corpo JSON com dois campos obrigatórios e um opcional:
{ "provider": "gemini", "api_key": "<the provider's key>", "label": "Overflow, EU" }A chave viaja uma vez. O nexus-auth encripta-a e informa o encaminhador, e a resposta transporta apenas a dica. A resposta é 201 com o ID da nova chave e a sua linha: "Adicionada. A chave Google Gemini ••••7f2q está no conjunto de IA da organização, e o AI Provider Router já pode encaminhar para ela." Uma etiqueta tem no máximo 100 caracteres, e uma chave é uma cadeia de caracteres sem espaços de, no máximo, 4096 caracteres. Qualquer outro campo no corpo, ou um campo que nomeie uma organização ou uma pessoa, é recusado.
A retirada requer um corpo vazio. O encaminhador deixa de encaminhar para a chave de imediato, e o nexus-auth guarda-a, listada como retirada, para que o seu histórico permaneça. Nada no conjunto é alguma vez eliminado.
| Recusa | HTTP | Quando |
|---|---|---|
VALIDATION_FAILED |
400 | Um corpo que não seja {provider, api_key, label?}, um fornecedor desconhecido ou a assinatura própria de uma pessoa oferecida como chave de organização |
AUTHORITY_EXCEEDED |
403 | O requerente não é proprietário nem administrador da organização |
RECORD_NOT_FOUND |
404 | Nenhuma chave com esse ID está no conjunto da organização |
TRANSITION_NOT_PERMITTED |
409 | A chave já foi retirada |
TENANT_NOT_A_PARAMETER |
403 | O corpo ou a consulta nomeou uma organização |
Estados das chaves
Cada chave no conjunto encontra-se num de seis estados. Apenas uma chave em utilização responde a uma conversa.
| Estado | O que significa |
|---|---|
in_use |
A chave responde, até à sua data de expiração, se a tiver. |
resting |
O encaminhador colocou-a em pausa após falhas, até uma hora definida. Entretanto, os pedidos vão para a chave seguinte. |
exhausted |
Esgotou o seu limite no fornecedor. |
invalid |
O fornecedor já não a aceita. |
expired |
Caducou na sua data de expiração. |
withdrawn |
Um administrador retirou-a. Permanece listada como histórico. |
Uma chave que falha fica em pausa durante 60 segundos. Após 5 falhas seguidas, o encaminhador desliga-a, transfere a sua quota-parte para as outras chaves e regista o aviso PROVIDER_KEY_SWITCHED_OFF. Ninguém é recusado enquanto outra chave puder responder.
Quando um fornecedor não tem nenhuma chave em utilização, o conjunto explica porquê ("Nenhuma chave em utilização: 1 retirada, 1 caducada"). Quando nenhum fornecedor no conjunto tem uma chave em utilização, uma conversa é recusada com NO_PROVIDER_FOR_ROLE (422) e a solução: um proprietário ou administrador adiciona uma chave de organização. Trata-se de um estado de configuração, e permanece no ecrã até que alguém o corrija.
Funções, política e preferências
O encaminhador pensa em funções. Cada pedido destina-se a uma de cinco: default, fast, reasoning, code ou long_context. Cada modelo está também num nível (tier), frontier, standard ou fast, e é preferido um nível superior quando a função o permite. A organização decide que fornecedor serve cada função (as suas atribuições de funções) e a ordem de recurso (fallback) quando um fornecedor falha (a sua escada de política de encaminhamento). Os administradores definem ambos na central de comutação de IA. O nexus-auth também os serve em /auth/org/<organisation-id>/settings/ai-provider/role-assignments e /auth/org/<organisation-id>/settings/ai-provider/routing-policy para uma chave de administrador que detenha ai_provider:manage.
Os requerentes podem indicar o que gostariam. Uma linha de competência (skill) pode transportar um fornecedor preferido e um modelo preferido, além de um perfil de capacidades. O encaminhador trata cada um de forma diferente:
- Um fornecedor preferido só é respeitado quando a organização tem esse fornecedor ativado e possui uma chave para ele. Caso contrário, o encaminhador substitui-o.
- Um modelo preferido é respeitado quando consta do catálogo desse fornecedor e se adequa ao perfil.
- Um perfil de capacidades é um filtro que nunca seleciona. Pode pedir uma janela de contexto mínima, utilização de ferramentas, visão, embeddings, contexto longo ou uma residência de dados. Tudo o que não o cumpra não é elegível.
O encaminhador escolhe numa ordem fixa. Respeita a preferência quando pode, depois tenta outro modelo do mesmo fornecedor, depois a atribuição de função e qualquer outro fornecedor com uma chave cujo catálogo se adeque. Se tiver sido indicado um perfil e nenhum catálogo se adequar a ele, o pedido é recusado com MODEL_CAPABILITY_UNAVAILABLE (422). Se nada estiver atribuído e nada corresponder, é NO_PROVIDER_FOR_ROLE (422). Não existe um modelo predefinido de último recurso. Uma função que não tenha configurado falha de forma explícita, com as próprias palavras do encaminhador a indicar o que definir.
A residência de dados é a única restrição que não pode ser contornada por substituição. Um perfil com eu_only é servido por um fornecedor da UE ou recusado. A Harrow define este bloqueio para toda a organização, e a central de comutação representa o segundo fornecedor alojado, que se encontra numa região dos EUA, como desligado.
Uma competência (skill) também pode fixar um modelo exato quando precisa desse modelo para funcionar. Mesmo assim, o encaminhador utiliza a própria chave da organização para o efeito, e sem uma nada responde. Um requerente nunca pode fazer o Nexus utilizar um fornecedor que a organização não tenha configurado.
Uma vez escolhido um fornecedor, a comutação por falha (failover) é uma questão separada. Um erro 429, um 5xx ou uma falha de rede faz descer o pedido na escada para o fornecedor seguinte. Um 400, 401, 403 ou 404 para de imediato, porque as credenciais e os formatos de pedido não se transferem entre fornecedores e uma nova tentativa consumiria quota para chegar à mesma falha.
Para ver o que o encaminhador escolheria antes de alguém fazer uma pergunta, leia GET /api/ai/routing-policy/effective no gateway com o próprio token de uma pessoa. Responde com o modelo para a organização com sessão iniciada, ou a recusa do encaminhador por palavras quando não existe nenhum, e não envia qualquer pedido a um modelo.
Monitorizar o encaminhador
A faixa de indicadores na parte inferior de cada página mostra o modelo em utilização ("Modelo: local"). Na versão Enterprise, A central de comutação de IA, em direto desenha o tráfego do encaminhador à medida que acontece: pedidos do assistente, trabalhos e aplicações a fluir através de funções para fornecedores e chaves, uma chave na sua pausa de 60 segundos desenhada a cinzento, uma chave desligada desenhada a vermelho e um recurso (fallback) ao fornecedor alojado quando o modelo local está ocupado. Ao lado do fluxo, apresenta gráficos de carga por fornecedor, pedidos por segundo e tempo de espera. Tomás mantém-na aberta durante a primeira semana após qualquer alteração à política de encaminhamento, porque uma atribuição de função errada aparece ali em poucos minutos como tráfego a ir para onde ninguém pretendia.
Na versão Community, a página Modelos de IA tem um botão Testar todos os modelos que verifica cada modelo configurado e assinala se responde. É a forma mais rápida de provar que uma nova chave funciona antes de alguém depender dela.
Incorporações
A pesquisa e o grafo de conhecimento transformam texto em vetores. Por predefinição, a instalação fá-lo com um modelo de embedding que corre dentro do cluster no processador, pelo que nenhum texto sai das instalações para gerar embeddings e uma organização não precisa de qualquer chave para o efeito. Utilizar um fornecedor alojado para embeddings é uma escolha que uma organização faz; passa então pelo mesmo conjunto e pelas mesmas regras.
Apenas três serviços podem pedir ao encaminhador embeddings ou reclassificação (reranking): nexus-graphrag, nexus-skills-engine e nexus-workflows. O GraphRAG gera embeddings como a organização à qual pertence o conteúdo, com as definições dessa organização, e não detém qualquer chave de fornecedor própria. Quando uma organização altera o seu modelo de embedding, o nexus-workflows executa o trabalho de regeneração de embeddings para os armazenamentos dessa organização.
As credenciais individuais permanecem pessoais
Algumas credenciais pertencem a uma pessoa. Uma assinatura Claude Max, com sessão iniciada através da própria conta dessa pessoa, é o caso comum. Tal credencial nunca é uma chave de organização: o conjunto recusa-a com VALIDATION_FAILED, nunca é listada na tabela de chaves da organização e nenhum ecrã de outra pessoa a mostra.
As chaves de modelos também nunca vão para mais lado nenhum. A página Chaves de dados externos, que guarda chaves para fontes de dados externas, recusa tudo o que se pareça com uma chave de modelo de IA com AI_PROVIDER_KEYS_BELONG_TO_ORG_POOL (422). Se o leitor de ficheiros encontrar chaves de modelos dentro de um documento ou configuração onde não pertencem, regista CREDENTIALS_IN_WRONG_PLACE e um administrador remove-as e substitui-as.
Scripts, REST e MCP
O Nexus tem três anfitriões públicos. Na Harrow, são console.harrow.example para a consola, api.harrow.example para o gateway e auth.harrow.example para o início de sessão. Os scripts e as ferramentas utilizam o segundo e o terceiro.
Chaves para scripts
Um script inicia sessão com uma chave criada em Definições, Chaves para scripts. Cada chave tem um nome, um alcance (por exemplo, "Iniciar apenas contagem do pátio por drone"), a pessoa que a criou e uma data de fim; uma organização pode bloquear a duração máxima que uma chave pode ter. O segredo é mostrado uma vez quando a chave é criada. Copie-o para o armazenamento de segredos do script, porque o Nexus guarda apenas os seus últimos quatro caracteres. Uma chave é retirada, nunca removida: para de imediato e permanece listada com todas as chamadas que efetuou. A rotação atribui à chave um novo segredo e mostra-o uma vez.
Cada chave tem a sua própria página com chamadas por dia, chamadas por serviço e um registo de atividade com hora, endereço, serviço e resultado. Uma chamada fora do alcance da chave é recusada e aparece no registo.
O nexus-auth serve as mesmas chaves a uma pessoa com sessão iniciada em https://auth.harrow.example/api-keys: criar e listar, depois ler, alterar, revogar ou rodar uma chave pelo seu ID.
REST através do gateway
Envie chamadas REST para https://api.harrow.example com Authorization: Bearer <token-or-key>. Cada chave tem de pertencer a uma organização. Uma chave sem organização é recusada com TOKEN_ORG_MISSING (403) por todos os serviços que verificam chaves através do nexus-auth.
Um requerente que faça pedidos com demasiada frequência recebe como resposta 429 com RATE_LIMITED, um cabeçalho Retry-After e o limite e a janela no corpo. Aguarde o número de segundos indicado. Na versão Enterprise, os administradores definem limites por chave, por aplicação e por unidade em Definições, Limites de taxa (consulte o capítulo 2.16, Segurança e redes).
MCP para ferramentas de IA
As ferramentas de IA que comunicam através do Model Context Protocol ligam-se a https://api.harrow.example/mcp. Iniciam sessão através do servidor OAuth 2.1 (OAuth é a norma aberta para autorização delegada) em https://auth.harrow.example, que suporta o registo de cliente pela própria ferramenta, pelo que uma ferramenta como o Claude Code ou o Cursor se regista a si própria e abre o navegador da pessoa para iniciar sessão. A ligação age então em nome dessa única pessoa, com os direitos dessa pessoa e nada mais. Uma pessoa com sessão iniciada pode obter uma configuração pronta a usar para uma ferramenta de linha de comandos a partir de https://auth.harrow.example/api/v1/mcp/cli-config.
As chamadas de ferramentas que precisam de um modelo passam pelo encaminhador como tudo o resto, sob a organização da pessoa.




