API de chatbot RAG — assistente de base de conhecimento com Claude em produção

A arquitetura moderna padrão de chatbot com base de conhecimento

A pesquisa tradicional em uma base de conhecimento retorna links; o usuário os lê. O RAG transforma isso em uma resposta conversacional única, com citações. Quando bem feito, os usuários obtêm respostas em 2 segundos, em vez de vasculhar 5 documentos. Quando mal feito, o chatbot alucina e seu CTO bane o projeto por um ano. Esta página mostra a diferença.

A stack mínima viável para produção

1. Armazenamento vetorial: pgvector se você já usa Postgres, Pinecone ou Qdrant para uma opção gerenciada
2. Embeddings: text-embedding-3-large, chamado diretamente na OpenAI — a Kunavo não oferece embeddings, e a chamada de embedding é uma requisição separada da chamada de geração de qualquer forma
3. Recuperação: híbrida (vetorial + BM25 com fusão recíproca de ranking)
4. Geração: Claude Sonnet 5 com cache_control no prompt do sistema
5. Interface: respostas em streaming, renderização de citações, fallback "Eu não sei"

from openai import OpenAI
client = OpenAI(api_key="sk-kn-...", base_url="https://api.kunavo.com/v1")

def chat(question: str, history: list[dict]) -> dict:
    chunks = hybrid_retrieve(question, k=5)  # vector + BM25
    context = "\n\n---\n\n".join(
        f"[doc:{c['id']}] {c['text']}" for c in chunks
    )
    resp = client.chat.completions.create(
        model="claude-sonnet-5",
        messages=[
            {"role": "system", "content": [{
                "type": "text",
                "text": (
                    "Answer only from Context. Cite [doc:N] for each claim. "
                    "If Context doesn't answer, say 'I don't have that.' "
                    "Be concise, no throat-clearing."
                ),
                "cache_control": {"type": "ephemeral"},
            }]},
            *history,
            {"role": "user", "content": f"# Context\n{context}\n\n# Q\n{question}"},
        ],
        max_tokens=600,
    )
    answer = resp.choices[0].message.content
    cited_ids = parse_citations(answer)  # extract [doc:N] references
    return {"answer": answer, "sources": [c for c in chunks if c["id"] in cited_ids]}

Custo em escala de produção

• Indexação inicial: ~US$ 0,25 para 5.000 documentos de 500 tokens cada
• 1.000 consultas/dia: ~US$ 210/mês com cache
• 10.000 consultas/dia: ~US$ 2.100/mês
• Usando Haiku 4.5 em vez de Sonnet: ~4 vezes mais barato, ~85% da qualidade das respostas

Veja a análise arquitetural completa no guia de implementação de RAG. Observações de ajuste específicas por idioma no aprofundamento sobre RAG em japonês e no guia de RAG em espanhol.

Os três padrões que realmente evitam alucinações

• Cite toda afirmação: tags [doc:42] na saída do modelo. Se o id citado não estiver no conjunto recuperado, o modelo alucinou — bloqueie e registre
• Recusa explícita no prompt do sistema: "Se o Contexto não responder, diga 'Eu não tenho essa informação.'" Sem isso, o modelo preenche a resposta com conhecimento geral
• Limite de saída de 600 tokens: respostas curtas geralmente são respostas precisas. É nas saídas mais longas que surgem invenções extras

O que lançar na semana 1 versus na semana 4

Comece em /app/signup

Uma recarga de US$ 10 cobre a indexação inicial de ~100 mil documentos e 1.500 consultas de teste — mais que suficiente para um protótipo funcional, e o saldo nunca expira. Depois, leia o guia completo de RAG para conhecer os padrões de produção.

Perguntas frequentes