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.
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 |
GoogleEncoder('text-embedding-004') |
GOOGLE_API_KEY |
- Las variables son las de LangChain, no la que declare
claveenconfig.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=1536paratext-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 enAZURE_OPENAI_ENDPOINTyAZURE_OPENAI_API_VERSION. SentenceTransformerEncodercalcula 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.
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:
"""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
exigirnireglas. Lo que importa es que cada documento quede con suarea. - Los embeddings no se escriben: los calcula el cliente al guardar cada fragmento, a partir
de su
texto.create_manylos pide todos juntos, y devuelve los fragmentos creados. tai-chat sql feedno 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¶
"""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_embeddinglo genera tai-sql para la columnaembedding: calcula el vector detextcon el mismo encoder y devuelve las filas más cercanas, de la más parecida a la menos, cada una con surecord(elFragmentoRead) y sudistance(menor es más parecido).- La regla de siempre:
exigirde las dos tablas que lee —el fragmento y, porincludes, su documento— yrls=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).
- Haz preguntas reales, unas que los documentos responden y otras que no.
- Mira las distancias: los fragmentos que responden quedan por debajo de un valor, y los que no vienen a cuento, por encima.
- Declara ese valor como
thresholdenvector_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 defind_similar_by_embeddingy defind_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.
Si la herramienta devuelve un fragmento de un documento que ese curl no devuelve, le falta rls=.