API de chatbot RAG — asistente de base de conocimientos basado en Claude en producción

La arquitectura moderna predeterminada para chatbots de bases de conocimiento

La búsqueda tradicional en una base de conocimiento devuelve enlaces; el usuario los lee. RAG lo convierte en una respuesta conversacional de un solo paso con citas. Bien hecho, los usuarios obtienen respuestas en 2 segundos en lugar de rebuscar en 5 documentos. Mal hecho, el chatbot alucina y tu CTO prohíbe el proyecto durante un año. Esta página explica la diferencia.

La pila mínima viable para producción

1. Almacén vectorial: pgvector si ya tienes Postgres; Pinecone o Qdrant para una opción gestionada
2. Embeddings: text-embedding-3-large, llamado directamente contra OpenAI; Kunavo no ofrece embeddings y la llamada de embeddings es una solicitud separada de la llamada de generación en cualquier caso
3. Recuperación: híbrida (vector + BM25 con fusión de rangos recíprocos)
4. Generación: Claude Sonnet 5 con cache_control en el prompt del sistema
5. Interfaz: respuestas en streaming, renderizado de citas y fallback «No lo sé»

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]}

Coste a escala de producción

• Indexación inicial: aproximadamente $0.25 para 5.000 documentos de 500 tokens cada uno
• 1.000 consultas/día: aproximadamente $210/mes con caché
• 10.000 consultas/día: aproximadamente $2.100/mes
• Si usas Haiku 4.5 en lugar de Sonnet: aproximadamente 4 veces más barato y con una calidad de respuesta de aproximadamente 85 %

Desglose completo de la arquitectura en la guía de implementación de RAG. Notas de ajuste específicas por idioma en el análisis profundo de RAG en japonés y la guía de RAG en español.

Los tres patrones que realmente evitan las alucinaciones

• Cita cada afirmación: etiquetas [doc:42] en la salida del modelo. Si el id citado no está en el conjunto recuperado, es una alucinación: bloquéala y regístrala
• Rechazo explícito en el prompt del sistema: «Si el contexto no responde, di “No tengo esa información”». Sin esto, el modelo completa la respuesta usando conocimiento del mundo
• Límite de salida de 600 tokens: las respuestas breves suelen ser respuestas precisas. Las invenciones adicionales aparecen sobre todo en salidas más largas

Qué enviar en la semana 1 frente a la semana 4

Empieza en /app/signup

Una recarga de $10 cubre la indexación inicial de aproximadamente 100.000 documentos y 1.500 consultas de prueba, más que suficiente para un prototipo funcional, y el saldo nunca caduca. Después, lee la guía completa de RAG para conocer los patrones de producción.

Preguntas frecuentes