Inferência LLM e prompts experimentais¶

Recomendado para leitura prévia

Protocolo de avaliação — desenho experimental, bateria e critérios de desfecho.
Runbook de reprodutibilidade — passos para repetir uma corrida com evidências.
Módulos Spring — estrutura de projetos e dependências.
Manifesto de prompts v1 — versões dos artefatos de prompt.
Schema context.json — campos obrigatórios por corrida.

Política de inferência v1¶

Parâmetro	Google (`gemini-3.5-flash`)	OpenAI (`gpt-5.4-nano`)	Registro em `context.json`
`temperature`	0	N/A (modelo de raciocínio)	`inferenceConfig.temperature` ou `null`
`temperatureSupported`	`true`	`false`	`inferenceConfig.temperatureSupported`
`topP`	omitido (`null`)	omitido (`null`)	`inferenceConfig.topP`
`topK`	omitido (default do provedor)	N/A	não registrar
`maxOutputTokens`	4096	4096	`inferenceConfig.maxOutputTokens`
`maxInputTokens`	limite do modelo (não fixar no harness v1)	idem	`null` ou omitido
`frequencyPenalty`	omitido / 0	omitido	não registrar v1
`presencePenalty`	omitido / 0	omitido	não registrar v1
`seed`	explícita por campanha	explícita por campanha	`seed` (raiz)

Regras:

temperature = 0 na campanha baseline v1 (Gemini). O default Spring AI para Google é 0,7 — sobrescrever explicitamente.
Não definir topP junto com temperature (recomendação Spring AI).
Modelos GPT-5 de raciocínio (gpt-5.4-nano) rejeitam temperature; registrar temperatureSupported: false e omitir o parâmetro no request.
seed permanece obrigatória, mas APIs comerciais não garantem determinismo total mesmo com temperature=0 — documentar como variância residual (ver § Limitações).

Referências de integração: documentação Spring AI para Google (Gemini) e OpenAI.

Montagem do prompt¶

Modo MCP (campaignId: mcp)
  system  = system-shared-v1.md + system-mcp-v1.md
  user    = user-template-v1.md
            + {{QUESTION_TEXT}}
            + (opcional) snapshot de metadados pós-tools

Modo baseline-static
  system  = system-shared-v1.md + system-baseline-v1.md
  user    = user-template-v1.md
            + {{QUESTION_TEXT}}
            + DDL offline (DDL integral anexo)

Diagrama:

flowchart TB
  subgraph shared [system-shared-v1]
    AntiHall[Anti-alucinação comum]
    Format[Formato PT-BR + SQL]
  end
  subgraph mcpMode [Modo MCP]
    McpRules[system-mcp-v1]
    Tools[Tools MCP até budget 10]
    UserMcp[user-template + pergunta]
  end
  subgraph baseMode [Modo baseline-static]
    BaseRules[system-baseline-v1]
    DDL[DDL offline anexo]
    UserBase[user-template + pergunta]
  end
  shared --> McpRules
  shared --> BaseRules
  McpRules --> Tools
  Tools --> UserMcp
  BaseRules --> DDL
  DDL --> UserBase

Regra de paridade (anti-confound)¶

Todo texto anti-alucinação estrutural reside em System prompt compartilhado v1 e deve ser idêntico entre modos.
Diferença material permitida:
MCP: instruções de descoberta via tools; sem DDL integral no prompt.
Baseline: instruções de uso do DDL anexo; toolBudget: 0.
É proibido enriquecer o system prompt MCP com regras textuais que não existam no baseline (ex.: «não invente tabelas» só no MCP).

Versionamento e congelamento¶

Campo	Valor v1
`promptVersion`	`"v1"`
`inferenceConfigVersion`	`"v1"`
Manifesto	Manifesto de prompts v1

Antes de qualquer corrida da campanha:

Congelar templates + properties + lista de tools em um commitHash.
Calcular promptArtifactsHash (SHA-256 da concatenação ordenada dos quatro arquivos .md do manifesto).
Gravar commitHash, promptVersion, inferenceConfigVersion, promptArtifactsHash e inferenceConfig em context.json de cada corrida.

Schema `context.json`¶

Canônico: Schema context.json v1.

Exemplos:

Baseline: Exemplo context baseline v1
MCP: Exemplo context MCP v1

Mapeamento Spring AI¶

Property (sugestão)	Campo `context.json`	Notas
`app.llm.provider`	`provider`	`google` ou `openai`
`app.llm.google.model-version`	`modelVersion`	ex.: `gemini-3.5-flash`
`app.llm.openai.model-version`	`modelVersion`	ex.: `gpt-5.4-nano`
`app.llm.google.temperature`	`inferenceConfig.temperature`	fixar `0`
`app.llm.openai.temperature`	—	omitir se `temperatureSupported: false`
`app.llm.*.max-output-tokens`	`inferenceConfig.maxOutputTokens`	`4096`
`app.llm.prompt.version`	`promptVersion`	`v1`
`app.llm.prompt.base-path`	`promptArtifacts.*`	raiz dos templates

O adaptador SpringAiLlmAdapter deve serializar a configuração efetiva do request e o hash dos templates em context.json via RunEvidencePort (ver Ports e adapters).

Equivalentes Spring AI (Google):

spring.ai.google.genai.chat.options.temperature=0
spring.ai.google.genai.chat.options.max-output-tokens=4096

OpenAI (gpt-5.4-nano): não definir temperature; definir max-output-tokens conforme documentação do modelo.

Limitações de validade¶

Determinismo imperfeito: temperature=0 e seed reduzem variância, mas provedores comerciais podem produzir SQL distinto entre corridas.
D12 (baseline): DDL integral no prompt aumenta contexto de entrada e constitui ameaça à validade interna do comparativo — ver Runbook de reprodutibilidade § Limitação D12.
Revisão humana: o rascunho operacional v1 dos templates está sujeito à aprovação do autor antes do congelamento da campanha.

Decisão formal: ADR-0003 Inferência LLM.

Recomendado para leitura posterior

Seguinte: Runbook de reprodutibilidade — passos para repetir uma corrida com evidências.