Este guia cobre a criação, gerenciamento e uso de credenciais de IA (segredos compartilhados) em LLMs, modelos de incorporação e ferramentas de IA personalizadas no plugin Discourse AI.
Nível de usuário necessário: Administrador
Resumo
As credenciais de IA oferecem uma maneira centralizada e segura de gerenciar segredos de autenticação — como chaves de API — em toda a configuração do Discourse AI. Em vez de colar chaves de API brutas em cada modelo de LLM, definição de incorporação ou ferramenta personalizada individualmente, você cria uma credencial uma única vez e a referencia sempre que necessário.
Ao rotacionar uma chave (por exemplo, sua chave de API da OpenAI), você a atualiza em um único local e cada LLM, incorporação ou ferramenta que usa a credencial detecta a alteração automaticamente.
Esta documentação abrange:
- Criação e gerenciamento de credenciais
- Vinculação de credenciais a LLMs e modelos de incorporação
- Uso de credenciais em ferramentas de IA personalizadas
- Proteção contra exclusão e ciclo de vida das credenciais
- A API para gerenciamento programático de credenciais
O que é uma credencial?
Uma credencial é um segredo nomeado e reutilizável armazenado centralmente no Discourse AI. Ela possui dois campos principais:
| Campo | Descrição |
|---|---|
| Nome | Um rótulo único e legível por humanos (por exemplo, “Chave de API da OpenAI”). Máximo de 100 caracteres. |
| Valor | O segredo real (chave de API, token, etc.). Máximo de 10.000 caracteres. |
Uma credencial pode ser referenciada por três tipos de entidades:
- Modelos de LLM — como a chave de API principal
- Definições de incorporação — como a chave de API principal
- Ferramentas de IA personalizadas — como vinculações de segredos nomeados acessadas via JavaScript
Além disso, certos parâmetros de provedor de LLM do tipo “segredo” (por exemplo, access_key_id para AWS Bedrock) também referenciam credenciais.
Criando e gerenciando credenciais
Acessando a página de credenciais
Navegue até Admin → Plugins → Discourse AI → Credenciais, ou visite diretamente /admin/plugins/discourse-ai/ai-secrets.
[screenshot placeholder: página de lista de credenciais mostrando as colunas nome, usado por e botão de editar]
Criando uma nova credencial
- Na página de credenciais, clique em “Nova credencial”.
- Digite um Nome para a credencial (por exemplo, “Chave de API da OpenAI”).
- Digite o Valor — a chave de API ou token real. Este campo é exibido como um campo de senha.
- Clique em “Salvar”.
[screenshot placeholder: formulário do editor de credenciais com os campos nome e valor]
Você também pode criar credenciais inline ao configurar um LLM, incorporação ou ferramenta. Um diálogo modal permite adicionar uma nova credencial sem sair da página atual, e a credencial aparece imediatamente na lista suspensa de seleção.
Editando uma credencial
- Na página de lista de credenciais, clique em “Editar” ao lado da credencial.
- Atualize o Nome ou o Valor conforme necessário.
- Clique em “Salvar”.
Ao visualizar uma credencial existente, o valor do segredo é mascarado (********) na visualização de lista. O valor real é mostrado apenas na página de edição da credencial individual.
Excluindo uma credencial
Uma credencial não pode ser excluída se estiver sendo referenciada atualmente por qualquer LLM, incorporação ou ferramenta. Se você tentar excluir uma credencial em uso, a interface exibirá uma mensagem listando as entidades que a referenciam, com links para suas páginas de edição.
Para excluir uma credencial:
- Primeiro, remova ou reatribua todas as referências à credencial de qualquer LLM, incorporação ou ferramenta.
- Volte à página de edição da credencial.
- Clique em “Excluir” e confirme a ação.
Vinculando credenciais a LLMs e incorporações
Modelos de LLM
Ao configurar um modelo de LLM na página de configurações de LLM, você pode selecionar uma credencial existente em uma lista suspensa em vez de colar uma chave de API diretamente. Em tempo de execução, o modelo resolve o segredo a partir da credencial vinculada.
Para segredos específicos do provedor — como o access_key_id da AWS Bedrock — o ID da credencial é armazenado dentro dos parâmetros do provedor e resolvido transparentemente quando o modelo faz solicitações de API.
Definições de incorporação
Os modelos de incorporação funcionam da mesma maneira. Ao configurar uma definição de incorporação, selecione uma credencial na lista suspensa. O modelo de incorporação valida que uma credencial ou uma chave de API inline esteja presente e usa o valor da credencial em tempo de execução.
Usando credenciais em ferramentas de IA personalizadas
Ferramentas de IA personalizadas usam um padrão de contrato e vinculação para segredos, o que mantém a definição da ferramenta portátil (exportável/importável) enquanto os segredos permanecem locais ao site.
Etapa 1: Declarar contratos de segredo
Ao criar ou editar uma ferramenta, você declara quais segredos a ferramenta requer adicionando entradas aos seus contratos de credencial. Cada entrada possui um alias — um identificador simples usando letras, números e sublinhados.
Na página do editor da ferramenta, clique em “Adicionar credencial” para adicionar uma nova entrada de contrato e dê a ela um nome de alias, por exemplo external_api_key.
[screenshot placeholder: editor de ferramenta mostrando campos de alias de credencial e seletores de credencial]
Nomes de alias devem corresponder ao padrão [a-zA-Z0-9_] e ser únicos dentro da ferramenta.
Etapa 2: Vincular credenciais a aliases
Ao lado de cada alias declarado na página de configuração da ferramenta, selecione uma credencial existente na lista suspensa. Isso cria uma vinculação entre o alias e a credencial.
A vinculação é validada para garantir:
- Que a credencial selecionada exista
- Que o alias esteja declarado nos contratos da ferramenta
Etapa 3: Acessar segredos em tempo de execução em JavaScript
Dentro do JavaScript de uma ferramenta, acesse segredos usando a 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);
}
Substitua external_api_key pelo nome do alias que você declarou nos contratos de credencial da ferramenta.
Todos os aliases declarados devem ter vinculações de credencial antes que a ferramenta possa ser executada. Se houver vinculações ausentes, a execução será bloqueada com uma mensagem de erro listando os aliases não vinculados.
Exemplo: uma ferramenta com múltiplas credenciais
Suponha que você esteja criando uma ferramenta que chama duas APIs diferentes. Declare dois contratos de credencial:
| Alias | Descrição |
|---|---|
weather_api_key |
Chave para a API de dados meteorológicos |
geocode_api_key |
Chave para a API de geocodificação |
Em seguida, vincule cada alias à credencial apropriada na página de configuração da ferramenta.
No 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);
}
Rastreamento de uso de credenciais
Cada credencial rastreia onde é referenciada. Na página de lista de credenciais, a coluna “Usado por” mostra links para cada LLM, incorporação ou ferramenta que está usando atualmente essa credencial.
Essa visibilidade ajuda você a:
- Entender o impacto antes de rotacionar ou atualizar um segredo
- Identificar credenciais não utilizadas que podem ser removidas com segurança
- Navegar rapidamente para as entidades que dependem de uma credencial
Referência da API
Todos os endpoints exigem autenticação de administrador e estão no caminho /admin/plugins/discourse-ai/ai-secrets.
| Método | Caminho | Descrição |
|---|---|---|
GET |
/ai-secrets |
Listar todas as credenciais (valores mascarados) |
GET |
/ai-secrets/:id |
Mostrar uma única credencial (valor não mascarado) |
POST |
/ai-secrets |
Criar uma nova credencial |
PUT |
/ai-secrets/:id |
Atualizar uma credencial |
DELETE |
/ai-secrets/:id |
Excluir uma credencial (retorna 409 se estiver em uso) |
Corpo da solicitação para criação e atualização:
{
"ai_secret": {
"name": "Chave de API da OpenAI",
"secret": "sk-..."
}
}
Todas as operações de criação, atualização e exclusão são registradas no log de ações da equipe. Os valores dos segredos são tratados como sensíveis e nunca são escritos nos logs.
Migração automática de chaves de API inline
Instalações existentes que anteriormente usavam chaves de API inline são migradas automaticamente. A migração:
- Lê todos os modelos de LLM e definições de incorporação não semeados que possuem uma chave de API inline.
- Deduplica por chave de API e provedor — se dois modelos compartilharem a mesma chave e provedor, eles recebem uma única credencial.
- Cria registros de credencial com nomes gerados automaticamente, como “Chave de API da OpenAI”, “Chave de API da AWS Bedrock”, etc.
- Atualiza os registros de modelo de LLM e definição de incorporação para referenciar as novas credenciais.
- Lida com valores
access_key_idda AWS Bedrock nos parâmetros do provedor — extraindo a chave bruta, criando uma credencial e substituindo o valor inline pelo ID da credencial.
Essa migração é executada automaticamente na atualização e é irreversível. Nenhuma ação manual é necessária.
Problemas comuns e soluções
“Esta credencial está atualmente em uso e não pode ser excluída”
Isso significa que um ou mais LLMs, incorporações ou ferramentas referenciam a credencial. Verifique a coluna “Usado por” na página de lista de credenciais para identificar e reatribuir ou remover essas referências antes de excluir.
“Vinculações de credencial obrigatórias ausentes” ao executar uma ferramenta
Todos os aliases de credencial declarados nos contratos de uma ferramenta devem ter vinculações. Abra a página de edição da ferramenta, verifique se cada alias tem uma credencial selecionada na lista suspensa e salve.
O valor da credencial é exibido como ********
Este é o comportamento esperado. Os valores dos segredos são mascarados nas visualizações de lista por segurança. Para visualizar ou editar o valor real, clique em “Editar” na credencial específica.
Rotacionei uma chave, mas os recursos de IA ainda falham
Após atualizar o valor de uma credencial, verifique se o teste de LLM (na página de configurações de LLM) foi aprovado. Se a nova chave tiver permissões diferentes ou pertencer a uma conta diferente, verifique os requisitos de configuração do provedor.
Perguntas frequentes (FAQs)
Posso ainda usar chaves de API inline em vez de credenciais?
Chaves de API inline legadas continuam funcionando para configurações existentes. No entanto, as credenciais são a abordagem recomendada porque simplificam a rotação de chaves e reduzem a duplicação.
Os valores das credenciais são criptografados em repouso?
Os valores das credenciais são armazenados no banco de dados. Eles seguem o mesmo modelo de segurança que outros dados sensíveis do Discourse. Certifique-se de que seu banco de dados esteja adequadamente protegido e que os backups sejam tratados de forma apropriada.
O que acontece quando importo uma ferramenta que usa credenciais?
As importações de ferramenta incluem os aliases dos contratos de credencial, mas não os valores reais dos segredos. Após importar uma ferramenta, você precisará criar ou selecionar credenciais para cada alias declarado na página de configuração da ferramenta.
Posso compartilhar uma única credencial entre vários LLMs?
Sim. Múltiplos LLMs e incorporações podem referenciar a mesma credencial. Isso é particularmente útil quando você usa a mesma chave de API do provedor em várias configurações de modelo.