mirror of
https://github.com/hoshikawa2/agent_platform_oci.git
synced 2026-09-07 10:13:46 +00:00
95 lines
4.4 KiB
Markdown
95 lines
4.4 KiB
Markdown
# RAG alternativo: Standard x KBDB Enterprise
|
|
|
|
O framework passa a suportar dois backends de retrieval pelo mesmo contrato `RagService`, sem alterar os agentes nem `_retrieve_rag_context()`.
|
|
|
|
## Seleção
|
|
|
|
```env
|
|
RAG_PROVIDER=standard # default: comportamento anterior
|
|
# ou
|
|
RAG_PROVIDER=kbdb # KBDB enterprise
|
|
```
|
|
|
|
A seleção é exclusiva por processo. Os dois RAGs não executam juntos e não compartilham vector store, graph store ou ingestão.
|
|
|
|
## `standard`
|
|
|
|
Mantém integralmente o RAG já existente no `agent_framework_oci`: `VECTOR_STORE_PROVIDER`, `GRAPH_STORE_PROVIDER`, embedding, query rewrite, compression, retrieval guardrails e geração continuam válidos.
|
|
|
|
## `kbdb`
|
|
|
|
O framework integra somente a porta estável de serving do projeto KBDB:
|
|
|
|
`PKG_KB_SERVING.SEARCH_KNOWLEDGE_BASE`
|
|
|
|
O pipeline enterprise continua externo ao runtime do agente e preserva sua própria arquitetura RAW → SILVER → GOLD, HVI/hybrid search, property graph, publicação, lifecycle, auditoria e observabilidade.
|
|
|
|
O envelope KBDB é adaptado para `RagResult`/`VectorDocument`; portanto os agentes existentes continuam chamando `_retrieve_rag_context()` e os retrieval guardrails do framework continuam depois do retrieval.
|
|
|
|
### Configuração
|
|
|
|
```env
|
|
RAG_PROVIDER=kbdb
|
|
RAG_TOP_K=5
|
|
KBDB_DB_USER=KB_USER
|
|
KBDB_DB_PASSWORD=...
|
|
KBDB_DB_DSN=...
|
|
KBDB_DB_WALLET_LOCATION=...
|
|
KBDB_DB_WALLET_PASSWORD=...
|
|
KBDB_SEARCH_TYPE=hybrid
|
|
KBDB_NODE_EXPANSION=true
|
|
KBDB_NODE_MAX_RELATED=8
|
|
KBDB_GRAPH_CROSS_REF=false
|
|
KBDB_MAX_CROSS_REF_HOPS=1
|
|
KBDB_DOCUMENT_TYPE=customer_safe
|
|
KBDB_METADATA_JSON=
|
|
KBDB_MIN_SCORE=
|
|
```
|
|
|
|
Quando `RAG_PROVIDER=kbdb`, `KBDB_DB_USER`, `KBDB_DB_PASSWORD` e `KBDB_DB_DSN` são obrigatórios. O KBDB usa conexão isolada porque pode residir em outro Autonomous. `KBDB_DB_DSN` segue a mesma semântica de `ADB_DSN`: use o alias TNS existente no `tnsnames.ora` da wallet indicada por `KBDB_DB_WALLET_LOCATION`, e não uma URL `tcps://...`.
|
|
|
|
## Isolamento e compatibilidade
|
|
|
|
- `RAG_PROVIDER=standard` não importa nem conecta ao KBDB.
|
|
- `RAG_PROVIDER=kbdb` não instancia vector/graph stores do RAG padrão.
|
|
- Ingestão por `RagService.add_documents()` não é permitida no modo KBDB: deve passar pelo pipeline/publicação KBDB.
|
|
- Query rewrite e context compression continuam opcionais e são aplicados pela camada comum do framework.
|
|
- `AgentRuntimeMixin._retrieve_rag_context()` e os agentes permanecem inalterados.
|
|
- Falhas do KBDB seguem a semântica existente do framework: retrieval é evidência auxiliar e a exceção é convertida em metadata técnica sem derrubar a jornada.
|
|
|
|
|
|
## Resposta direta de tool e RAG
|
|
|
|
O framework não considera mais que um resultado MCP estruturado é, por si só, uma resposta suficiente ao usuário.
|
|
|
|
Uma política `response.renderer` define somente **como** apresentar o resultado. Ela não encerra o fluxo antes de RAG/LLM. Para uma tool deliberadamente produzir uma resposta final direta, a aplicação deve declarar explicitamente:
|
|
|
|
```yaml
|
|
response:
|
|
mode: renderer
|
|
renderer: meu.renderer
|
|
direct: true
|
|
```
|
|
|
|
Sem `direct: true`, o resultado da tool permanece como evidência MCP e o fluxo segue para `_retrieve_rag_context()` e composição LLM. Isso permite, por exemplo, que uma consulta operacional de plano seja combinada com conhecimento documental do KBDB quando a pergunta pedir regras, políticas ou explicações.
|
|
|
|
O core do framework não possui fallback por nome de tool (`consultar_plano`, `consultar_pedido`, etc.). Regras de apresentação pertencem à aplicação/domínio.
|
|
|
|
|
|
## Suficiência MCP e grounding
|
|
|
|
Um resultado MCP bem-sucedido **não** faz o framework pular RAG automaticamente.
|
|
O domínio só pode declarar suficiência documental explicitamente no payload com
|
|
`rag_sufficient=true` ou `knowledge_sufficient=true`. Essa decisão é genérica e
|
|
não depende do nome da tool nem de palavras-chave de telecom/retail.
|
|
|
|
No provider `kbdb`, `KBDB_GROUNDED_ONLY=true` é o padrão. Quando a busca KBDB
|
|
retorna vazia, bloqueada ou com erro, a composição LLM pode usar fatos comprovados
|
|
por MCP/business context, mas não pode completar a parte documental com conhecimento
|
|
paramétrico do modelo. Deve informar que não há evidência suficiente na base.
|
|
|
|
Eventos do ProductAgent registram `IC.PRODUCT_RAG_CONTEXT_EVALUATED` em toda
|
|
tentativa/decisão e `IC.PRODUCT_RAG_CONTEXT_RETRIEVED` somente quando há contexto
|
|
recuperado. Os metadados incluem `provider`, `status`, `document_count`, `reason`,
|
|
`error`, `query`, `namespace` e `latency_ms`.
|