Saltar a contenido

Buscar en documentos

Las herramientas de Herramientas que leen datos buscan por valores: las averías abiertas de la L2, las de este mes. Hay preguntas que no se responden así: «¿cada cuántas horas se engrasa el torno?», «¿con cuánta antelación se piden las vacaciones?». La respuesta está escrita en un manual o en una norma, y nadie la pregunta con las mismas palabras con que está escrita.

Para esas, la herramienta busca por significado: el texto de los documentos y el de la pregunta se convierten en vectores (embeddings), y se devuelven los trozos cuyos vectores están más cerca del de la pregunta. El modelo responde con esos trozos delante. Es lo que se suele llamar RAG.

tai-sql ya sabe hacer las dos mitades: guardar el vector junto al texto y buscar por cercanía. Lo que explica esta página es cómo montarlo en el chatbot sin saltarse lo de siempre: el asistente solo encuentra lo que el usuario que pregunta puede leer.

La referencia está en tai-sql

Esta página es el camino para el chatbot. Todos los parámetros de vector_column(), los encoders y las métricas están en el manual de tai-sql: Columnas vectoriales y Búsqueda vectorial.

Lo que hace falta

Dónde Por qué
pgvector en PostgreSQL La base de datos El tipo vector y su índice. push crea la extensión si el usuario de la base de datos puede; si no, falla diciendo qué ejecutar
pgvector en el entorno de tai-chat Donde ejecutas tai-chat sql … push lo necesita para leer las columnas vectoriales: pip install pgvector
pgvector en la API chatbot/api Lo importa el cliente generado: cd chatbot/api && poetry add pgvector
La clave del proveedor de embeddings El .env de la raíz La lee el encoder en la API, ver abajo

En una base de datos gestionada, la extensión se habilita antes

En Azure Database for PostgreSQL hay que añadir VECTOR al parámetro del servidor azure.extensions antes del primer push; sin eso, ni un administrador puede crearla. Otros proveedores tienen su equivalente. Para el PostgreSQL del docker-compose.yaml, la imagen comentada ya es pgvector/pgvector.

1. El schema

Un documento entero no se convierte en un vector: los modelos de embeddings tienen un límite de entrada, y el vector de un manual de cuarenta páginas no se parece a ninguna pregunta concreta. Se guarda troceado: cada fragmento con su vector, y colgando del documento del que sale.

database/schemas/conocimiento.py
from __future__ import annotations
from tai_sql import *
from tai_sql.generators import *

datasource(
    provider=env('MAIN_DATABASE_URL'),
    schema='conocimiento',
    syntax='v2',
    operative_fields=True,
)

generate(PythonClientGenerator(output_dir=['database/database']))


class Documento(Table):
    """Un documento de la base de conocimiento: un manual, un procedimiento, una norma"""
    __tablename__ = "documento"

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    titulo: col[str] = column(description='El título, tal como se cita')
    origen: col[str] = column(unique=True, description='De dónde sale: la ruta o la URL del original')
    area: col[str] = column(index=True, description='mantenimiento, calidad, rrhh…')

    fragmentos: onetomany[Fragmento]


class Fragmento(Table):
    """Un trozo de un documento, con su embedding: lo que se busca por significado"""
    __tablename__ = "fragmento"

    id: col[bigint] = column(primary_key=True, autoincrement=True)
    orden: col[int] = column(description='Su posición en el documento')
    texto: col[text] = column(description='El texto del fragmento')
    embedding: col[vector | None] = vector_column(
        source='texto',                                  # se calcula de `texto` al escribir
        encoder=OpenAIEncoder('text-embedding-3-small'),  # 1536 dimensiones, deducidas
        metric='cosine',
        index=True,                                      # índice HNSW
    )

    documento_id: col[bigint]
    documento: manytoone[Documento] = relation(fields=['documento_id'], references=['id'], backref='fragmentos')
  • source='texto': el cliente generado calcula el embedding al crear o modificar un fragmento. Nadie escribe vectores a mano.
  • index=True: sin índice, cada búsqueda compara con todos los fragmentos. Con unos pocos miles no se nota; con cientos de miles, sí.
  • Sin threshold, de momento. El umbral se decide mirando distancias reales, ver Afinar.

El encoder

El encoder es el modelo que convierte texto en vectores. Lo normal es usar el del proveedor que ya usa el chatbot: su librería ya está en la API (init instala langchain-openai y langchain-google-genai) y su clave ya está en el .env.

Si el chatbot usa Encoder Variables de entorno que lee
OpenAI OpenAIEncoder('text-embedding-3-small') OPENAI_API_KEY
Azure OpenAI AzureOpenAIEncoder('<despliegue>', dimensions=1536, azure_endpoint='https://…', api_version='…') AZURE_OPENAI_API_KEY
Google GoogleEncoder('text-embedding-004') GOOGLE_API_KEY
  • Las variables son las de LangChain, no la que declare clave en config.yaml. Si tus modelos leen la clave de otra variable, el encoder necesita además la suya, en local y en el despliegue.
  • En Azure, el primer argumento es el nombre del despliegue del modelo de embeddings, que es distinto del del chat. Como tai-sql no puede deducir de ese nombre cuántas dimensiones tiene, se declaran (dimensions=1536 para text-embedding-3-small); sin ellas, el schema no carga. El endpoint y la versión pueden ir en el schema, porque no son secretos, o en AZURE_OPENAI_ENDPOINT y AZURE_OPENAI_API_VERSION.
  • SentenceTransformerEncoder calcula los embeddings dentro de la API, sin proveedor, pero mete PyTorch en su imagen y el modelo en su memoria. Solo compensa si los textos no pueden salir de la empresa.

Elegir el encoder es para siempre, o casi

Los vectores de dos modelos distintos no se pueden comparar. Cambiar de encoder obliga a recalcular todos los fragmentos: borrar y volver a cargar los documentos.

2. La base de datos y el cliente

pip install pgvector                    # en el entorno de tai-chat, una vez
tai-chat sql push -s conocimiento       # la extensión, las tablas y el índice
tai-chat api generate -s conocimiento   # api.database.conocimiento, su CRUD y sus tipos
cd chatbot/api && poetry add pgvector   # lo que importa el cliente generado

Como con cualquier schema del repositorio, tai-chat db push no lo lleva: es del proyecto, no del chatbot.

Si push dice «Error interno de tai-sql: ImportError: pgvector…»

Falta el pip install pgvector en el entorno donde se ejecuta tai-chat. El mensaje es de tai-sql y propone pip install 'tai-sql', que no basta.

La búsqueda por significado no tiene endpoint: tai-api no la expone por HTTP. Se usa desde el cliente de Python, que es justo lo que usa una herramienta.

3. Quién puede leer qué

Los permisos son los de cualquier tabla. Lo que cambia es dónde se pone la regla de fila: en el documento, porque el fragmento cuelga de él. tai-api aplica las reglas de una tabla a todo lo que cuelga de ella por relaciones many-to-one, así que la del documento acota también sus fragmentos.

api/rbac/chatbot.py
from tai_api.rbac import source, role, app_permission, owner, rls
from rbac.tables.chatbot import (
    ...,
    Documento, Fragmento,
)

source(realm_name="chatbot", dbschemas=["chatbot", "conocimiento"])

# cada usuario ve los documentos de sus áreas: el atributo rls.conocimiento.documento.area
rls(target_schema="conocimiento", target_model="documento", target_field="area")

role(
    name="Tecnico",
    description="Chatea y consulta la documentación",
    api_permissions=[
        Chat.READ, Mensaje.READ, TokensMensaje.READ,
        Documento.READ, Fragmento.READ,
    ],
)
tai-chat api generate               # las constantes Documento y Fragmento
tai-chat api rbac push -r chatbot   # los permisos y el rol, a la base de datos

Sin el atributo, lo ve todo

Con rls(), un usuario que no tiene el atributo (null) no está acotado por la regla, y uno con la lista vacía ([]) no ve nada. Ver Filtrado por fila en tai-api. Si toda la documentación es para todos, no hace falta ninguna regla: basta el permiso de lectura.

4. Cargar los documentos

Los documentos se cargan con un script que usa el cliente de la API, y que se vuelve a ejecutar cuando cambian. Este lee los .md y .txt de una carpeta, los trocea por párrafos y sustituye lo que hubiera de cada fichero:

chatbot/api/cargar_documentos.py
"""Carga en el schema `conocimiento` los .md y .txt de una carpeta, troceados.

    python cargar_documentos.py <carpeta> --area <area>

Volver a cargar un fichero lo sustituye: lo que cambió en el original, cambia aquí.
"""
import argparse
import asyncio
from pathlib import Path

from api.database.conocimiento import (
    DocumentoAsyncDAO,
    DocumentoCreate,
    FragmentoAsyncDAO,
    FragmentoCreate,
)

#: Caracteres por fragmento, más o menos: un fragmento no parte un párrafo.
TAMAÑO = 1500


def trocear(texto: str) -> list[str]:
    fragmentos, actual = [], ""
    for parrafo in (p.strip() for p in texto.split("\n\n")):
        if not parrafo:
            continue
        if actual and len(actual) + len(parrafo) > TAMAÑO:
            fragmentos.append(actual)
            actual = ""
        actual = f"{actual}\n\n{parrafo}" if actual else parrafo
    if actual:
        fragmentos.append(actual)
    return fragmentos


async def cargar(fichero: Path, area: str) -> int:
    origen = str(fichero.resolve())
    for previo in await DocumentoAsyncDAO.find_many(origen=origen):
        await DocumentoAsyncDAO.delete(previo.id)       # sus fragmentos se van con él
    documento = await DocumentoAsyncDAO.create(
        DocumentoCreate(titulo=fichero.stem, origen=origen, area=area)
    )
    fragmentos = await FragmentoAsyncDAO.create_many([
        FragmentoCreate(documento_id=documento.id, orden=i, texto=texto)
        for i, texto in enumerate(trocear(fichero.read_text(encoding="utf-8")))
    ])
    return len(fragmentos)


async def main(carpeta: Path, area: str):
    for fichero in sorted([*carpeta.rglob("*.md"), *carpeta.rglob("*.txt")]):
        print(f"{fichero.name}: {await cargar(fichero, area)} fragmentos")


if __name__ == "__main__":
    argumentos = argparse.ArgumentParser()
    argumentos.add_argument("carpeta", type=Path)
    argumentos.add_argument("--area", required=True)
    a = argumentos.parse_args()
    asyncio.run(main(a.carpeta, a.area))
cd chatbot/api
set -a && . ../../.env && set +a
poetry run python cargar_documentos.py ../../manuales/mantenimiento --area mantenimiento
  • No es una herramienta: lo ejecuta una persona con las credenciales de la base de datos, así que no lleva exigir ni reglas. Lo que importa es que cada documento quede con su area.
  • Los embeddings no se escriben: los calcula el cliente al guardar cada fragmento, a partir de su texto. create_many los pide todos juntos, y devuelve los fragmentos creados.
  • tai-chat sql feed no sirve aquí: no calcula embeddings, y se para si una columna vectorial con encoder llega sin valor.
  • Un PDF o un Word se convierten antes a texto, con la librería que prefieras (pypdf, python-docx), y el resto es igual. Trocear por párrafos es el punto de partida; con títulos claros, trocear por secciones suele funcionar mejor.

5. La herramienta

agente/herramientas/documentos.py
"""Los documentos de la empresa, buscados como el usuario que pregunta."""
from langchain.tools import ToolRuntime
from langchain_core.tools import tool

from api.database.conocimiento import FragmentoAsyncDAO

from ..contexto import Contexto


@tool(parse_docstring=True)
async def buscar_en_documentos(pregunta: str, runtime: ToolRuntime[Contexto]) -> dict:
    """Busca en los manuales, procedimientos y normas de la empresa los fragmentos que mejor
    responden a una pregunta. Úsala para cualquier pregunta sobre cómo se hace algo o qué dice
    una norma, y responde solo con lo que devuelva, citando el documento.

    Args:
        pregunta: La pregunta completa, con sus términos: «cada cuántas horas se engrasa el torno de la L2».
    """
    contexto = runtime.context
    contexto.exigir("read", "fragmento")
    contexto.exigir("read", "documento")
    resultados = await FragmentoAsyncDAO.find_similar_by_embedding(
        text=pregunta,
        limit=5,
        includes=["documento"],
        rls=contexto.reglas("conocimiento"),
    )
    return {
        "fragmentos": [
            {
                "documento": r["record"].documento.titulo,
                "texto": r["record"].texto,
                "distancia": round(r["distance"], 3),
            }
            for r in resultados
        ],
    }

Y en la lista tools de agente/herramientas/__init__.py, como cualquier otra.

  • find_similar_by_embedding lo genera tai-sql para la columna embedding: calcula el vector de text con el mismo encoder y devuelve las filas más cercanas, de la más parecida a la menos, cada una con su record (el FragmentoRead) y su distance (menor es más parecido).
  • La regla de siempre: exigir de las dos tablas que lee —el fragmento y, por includes, su documento— y rls= en la consulta. Con eso, un usuario de mantenimiento no encuentra nada de RRHH, por mucho que su pregunta se parezca.
  • Cinco fragmentos de unos 1500 caracteres son unos 2000 tokens de entrada por búsqueda, que se quedan en la memoria de la conversación. Más fragmentos no suelen dar mejores respuestas.
  • El título del documento va en el resultado para que el modelo lo cite, y la distancia para poder afinar.

Para que el asistente la use sin dudar, dilo también en el prompt de config.yaml: «Para cualquier pregunta sobre procedimientos o normas, busca primero con buscar_en_documentos y responde solo con lo que encuentre».

Combinarla con filtros

find_similar_by_embedding solo busca por significado. Si además hay que filtrar por columnas del fragmento, find_many acepta el texto en el parámetro de la columna vectorial y ordena por distancia:

fragmentos = await FragmentoAsyncDAO.find_many(
    embedding=pregunta,                    # por significado
    documento_id=documento_id,             # y solo de este documento
    includes=["documento"],
    rls=contexto.reglas("conocimiento"),
    limit=5,
)
# cada fragmento lleva su distancia en fragmento.vector_search.combined_score

Escribir desde una herramienta

Una herramienta también puede crear fragmentos —«guarda esta nota en la documentación»—. El DAO asíncrono calcula el embedding con await, así que la API no se para mientras responde el proveedor. Lo demás es lo de Escribir: el permiso de la acción, el documento padre acotado por las reglas y username_context.

Afinar

Con el permiso app-lab, el front enseña debajo de cada respuesta lo que devolvió la herramienta, con la distancia de cada fragmento. Con metric='cosine' va de 0 (idénticos) a 2 (opuestos).

  1. Haz preguntas reales, unas que los documentos responden y otras que no.
  2. Mira las distancias: los fragmentos que responden quedan por debajo de un valor, y los que no vienen a cuento, por encima.
  3. Declara ese valor como threshold en vector_column() y regenera el cliente de la API (tai-chat api generate): no cambia nada en la base de datos. Pasa a ser el umbral por defecto de find_similar_by_embedding y de find_many: lo que esté más lejos no se devuelve.

Con umbral, una pregunta que los documentos no responden devuelve una lista vacía, y el modelo puede decir que no lo sabe en vez de responder con el fragmento menos malo.

Si las respuestas fallan aunque el fragmento correcto exista, el problema suele estar en los fragmentos, no en la búsqueda: demasiado largos (mezclan temas), demasiado cortos (pierden el contexto) o sin el título de su sección.

Lo que cuesta

  • Cada búsqueda es una llamada al modelo de embeddings, y cargar un documento, una por fragmento. Son baratas comparadas con el chat, pero no se apuntan en el consumo del chatbot: no son el modelo de la respuesta ni tienen su tarifa (ver Lo que gasta una herramienta). Las factura el proveedor directamente.
  • La primera búsqueda de cada proceso es algo más lenta: el cliente del encoder se crea al usarse.

Probar el aislamiento

Igual que con cualquier herramienta que lee datos: dos usuarios con áreas distintas hacen la misma pregunta, y cada uno solo debe recibir fragmentos de documentos que ve por la API.

curl -s localhost:8000/conocimiento/documento -H "Authorization: Bearer $TOKEN_ANA"

Si la herramienta devuelve un fragmento de un documento que ese curl no devuelve, le falta rls=.