Configuração LLM
O Doggy fornece um sistema gráfico de gestão de configuração LLM, com suporte para configuração flexível de múltiplos fornecedores, modelos e papéis, e alternância dinâmica em runtime, fornecendo suporte de modelos unificado para as funcionalidades de IA.
Visão geral
O sistema de configuração LLM localiza-se em src/Service/Platform/Llm/ e inspira-se no design Platform do Symfony AI Bundle:
- Suporte de múltiplos fornecedores: OpenAI, Azure, Anthropic, Ollama, gateways personalizados compatíveis com OpenAI
- Gestão gráfica: sem configuração YAML, gestão dinâmica através do backoffice
- Separação de papéis: a configuração é desacoplada da utilização; os papéis ligam modelos
- Criptografia de chaves: a API Key é armazenada encriptada, sem contacto com o frontend
Modelo de dados
LlmProvider (configuração de fornecedor)
| Campo | Tipo | Descrição |
|---|---|---|
| name | string | Nome de exibição, ex.: "GPT-4o" |
| provider | string | Identificador do fornecedor: openai / anthropic / azure / ollama / custom |
| model | string | Nome do modelo: gpt-4o / claude-3-5-sonnet / ... |
| apiKey | encrypted | API Key (armazenada encriptada) |
| apiEndpoint | string | Endpoint da API (opcional) |
| options | JSON | Parâmetros adicionais: temperature, max_tokens, top_p, etc. |
| isEnabled | boolean | Se está ativado |
| sortOrder | int | Ordenação |
LlmRole (papel/utilização)
| Campo | Tipo | Descrição |
|---|---|---|
| code | string | Código do papel: view_editor / entity_generation / workflow_analysis / query_assistant / chat / coding |
| label | string | Nome de exibição |
| providerId | UUID | Configuração de modelo ligada |
| systemPrompt | text | Prompt de sistema desse papel |
| options | JSON | Substituição de parâmetros ao nível do papel |
| isEnabled | boolean | Se está ativado |
Planeamento das utilizações dos papéis
| Código do papel | Utilização | Modelo recomendado |
|---|---|---|
| view_editor | Assistente IA do designer de vistas | gpt-4o / claude-3.5-sonnet |
| entity_generation | Geração de entidades assistida por IA | gpt-4o-mini |
| workflow_analysis | Análise e sugestões de fluxos de trabalho | gpt-4o |
| query_assistant | Linguagem natural → consulta de dados | gpt-4o-mini |
| chat | Assistente de conversação IA genérico | gpt-4o-mini |
| coding | Geração de código (Twig/JS/PHP) | gpt-4o / claude-3.5-sonnet |
Cadeia de invocação
LlmRouter::chatByRole(roleCode, messages, opts)
├─ Consulta LlmRole(code) → obtém o LlmProvider ligado
├─ LlmGatewayFactory::create(provider) → instancia o adaptador
├─ Descifra a API Key (LlmEncryptor)
└─ Invoca a API LLM (suporta chamadas de ferramentas, resposta em streaming)LlmGatewayFactory
Roteia automaticamente o adaptador com base no campo LlmProvider.provider:
| provider | Adaptador | Descrição |
|---|---|---|
| openai | OpenAiGateway | Interface compatível com OpenAI |
| anthropic | AnthropicGateway | API Anthropic Claude |
| azure | AzureGateway | Azure OpenAI |
| ollama | OllamaGateway | Ollama local |
| custom | CustomGateway | Gateway personalizado compatível com OpenAI |
Failover
LlmRouter suporta chatByRoleWithFallback: quando o fornecedor principal falha, degrada automaticamente para o modelo de reserva.
Interface de administração
Entrada: Definições do sistema → Configuração LLM (/admin/platform/llm-config)
Página de listagem
- Exibição dos fornecedores em cartões; um fornecedor pode corresponder a várias variantes de modelo
- Mostra diretamente os papéis/utilizações ligados ao modelo
- Alternância ativar/desativar com interruptor
- Ordenação por arrastar-e-soltar
Formulário de edição
- Nome, fornecedor, modelo, API Key (armazenamento encriptado), endpoint
- Gestão de papéis (LlmRoleType): código do papel, prompt de sistema, ligação de modelo
Criptografia de chaves
LlmEncryptor encripta e descifra a API Key com a chave de encriptação da plataforma. A chave reside apenas no servidor e o frontend nunca contacta a chave original:
php
// No armazenamento
$encrypted = $llmEncryptor->encrypt($apiKey);
// Na invocação
$apiKey = $llmEncryptor->decrypt($provider->getApiKey());Integração com o assistente IA
O assistente IA (ver Assistente IA) reutiliza o sistema LlmRole/LlmProvider:
Frontend → POST /api/admin/ai/chat
→ LlmRouter.chatByRole(roleCode, messages)
→ Consulta LlmRole → LlmGatewayFactory → API LLM- A API Key existe apenas no servidor (armazenamento encriptado na base de dados)
- A alternância de modelos é feita no backoffice, sem alterar código
- O roteamento por múltiplos fornecedores é feito automaticamente pelo LlmGatewayFactory
Ficheiros relacionados
| Ficheiro | Responsabilidade |
|---|---|
src/Service/Platform/Llm/LlmGatewayInterface.php | Interface de gateway |
src/Service/Platform/Llm/LlmGatewayFactory.php | Fábrica de adaptadores |
src/Service/Platform/Llm/LlmRouter.php | Roteamento por papel + failover |
src/Service/Platform/Llm/ModelRegistry.php | Registo de modelos |
src/Service/Platform/LlmEncryptor.php | Encriptação/descifração da API Key |
src/Entity/Platform/LlmProvider.php | Entidade de configuração do fornecedor |
src/Entity/Platform/LlmRole.php | Entidade de configuração do papel |
src/Controller/Admin/Platform/LlmConfigController.php | Controlador da interface de administração |