Conceptos básicos

Entender cuatro piezas basta para sacar partido al producto.

Fuente (source)

Una fuente es el origen del conocimiento del bot: una URL, un PDF, un repositorio de GitHub, una base de Notion, una carpeta de Drive. Cada fuente genera uno o varios documentos. Las fuentes pueden re-indexarse periódicamente: rag.art marca next_crawl_at = now + 7d tras una ingesta correcta y un cron vuelve a recogerla.

Documento (document)

Un documento es un "archivo lógico" dentro de la plataforma. Un PDF es un documento; una URL crawled genera un documento por página; un repositorio de GitHub genera un documento por archivo relevante (código + markdown). Cada documento tiene un estado (pending, processing, ready, failed) visible desde /documents.

Chunk

Un chunk es un fragmento ~500 tokens de texto. El ingeste divide cada documento en chunks con overlap, porque los modelos tienen una ventana de contexto limitada y porque la similitud semántica se calcula mejor a nivel de fragmento. Cada chunk:

• Se convierte a un vector (embedding).
• Se asocia al documento y al bot mediante bot_documents.
• Guarda la localización exacta dentro del archivo original (página, línea, URL) para poder generar la cita.

Embedding

Un embedding es un vector numérico que representa el significado del chunk en un espacio de 1 536 dimensiones (modelo por defecto: text-embedding-3-small de OpenAI). Al consultar, tu pregunta también se convierte a embedding y se busca por similitud coseno los N chunks más parecidos (N típico = 8). Esos chunks se pasan como contexto al LLM.

Cita (citation)

Cada respuesta del bot incluye las fuentes de donde proviene la información. Una cita es un par (chunk, documento, localización) que el UI muestra como "ver fuente". Es el antídoto contra la alucinación: si el usuario duda, abre la cita y verifica. Internamente la cita se entrega al modelo con un identificador [1], [2]… y el modelo está instruido para referenciarlos.

Allowlist de dominio

Si pones tu widget en acme.com, puedes restringir el endpoint de chat para que solo sirva peticiones desde ese dominio. Eso evita que un tercero incruste tu bot y te consuma cuota. Se configura en /bots/<id>?tab=security.

Cuota y créditos

• El plan determina cuántos mensajes/páginas/bots están incluidos al mes.
• Cada operación costosa (ingesta, mensaje) debita microcréditos del wallet del dueño del bot (no del usuario final que chatea).
• 1 crédito = 1 000 microcréditos. Los precios en la UI se muestran en créditos.
• Si consumes todos los créditos del plan, el bot deja de responder hasta la renovación mensual; puedes comprar un top-up puntual al momento (1.000 créditos por €4). No hay cobro automático por consumo extra.