Ir al contenido principal
Español— Elegir un idioma
Menú

Herramienta document_library: Preguntas y respuestas sobre tus archivos

Lección 11 de 18 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. RAG integrado de Mistral
  2. Crear una biblioteca de documentos
  3. Subir documentos
  4. Crear un agente con una biblioteca de documentos
  5. Consultar los documentos
  6. Gestionar bibliotecas
  7. Del soporte interno al análisis de contratos
  8. Preparar las fuentes y aislar las bibliotecas
  9. Puntos clave

Lección actualizada el 3 de noviembre de 2026 basada en el SDK mistralai 3.7.0: los documentos de la biblioteca se gestionan mediante client.beta.libraries.documents (upload, list, delete). Los métodos add_document, list_documents y remove_document de la versión anterior ya no existen, y las cargas se realizan ahora directamente en la biblioteca. Fuente: client-python.

RAG integrado de Mistral

La herramienta document_library es un sistema de Generación Aumentada por Recuperación (RAG) integrado directamente en la API de Agents. Tu agente accede a los documentos que has subido a la nube de Mistral, recupera los pasajes relevantes y formula su respuesta con citas. La diferencia respecto a una solución RAG desarrollada internamente es significativa: no necesitas alojar una base de datos vectorial, mantener una canalización de incrustaciones (embeddings) ni ajustar una estrategia de fragmentación. Simplemente subes los archivos, declaras la herramienta al crear el agente y dejas que el modelo decida cuándo consultar la biblioteca.

Crear una biblioteca de documentos

Una biblioteca es el contenedor que alberga tus documentos. Debes crearla con una única llamada a la API antes de subir cualquier archivo.

from mistralai.client import Mistral
import os

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Crear una biblioteca
library = client.beta.libraries.create(
    name="Documentación técnica",
    description="Manuales de producto y especificaciones técnicas."
)

print(f"ID de la biblioteca: {library.id}")

Toma nota del ID devuelto: es lo que debes pasar al agente. No existe ningún atajo utilizando el nombre de la biblioteca. Si tu equipo gestiona bibliotecas separadas para RR. HH., asuntos legales y documentación técnica, almacena estos IDs en tu configuración igual que harías con las cadenas de conexión.

Subir documentos

La carga se realiza en dos pasos: primero, el archivo se deposita en el espacio Files con un purpose explícito; luego, se adjunta a la biblioteca.

# Subir un PDF directamente a la biblioteca
with open("product-manual.pdf", "rb") as f:
    document = client.beta.libraries.documents.upload(
        library_id=library.id,
        file={"file_name": "product-manual.pdf", "content": f},
    )

print(f"Documento {document.id}: {document.processing_status}")

Los formatos admitidos incluyen PDF, texto plano y otros tipos de documentos comunes.

Crear un agente con una biblioteca de documentos

agent = client.beta.agents.create(
    model="mistral-medium-latest",
    name="Agente de documentación",
    instructions="""Eres un asistente de documentación.
- Responde únicamente utilizando documentos de la biblioteca
- Cita los pasajes relevantes
- Si la información no está en los documentos, indícalo claramente""",
    tools=[{
        "type": "document_library",
        "library_ids": [library.id]
    }]
)

El parámetro library_ids es una lista: puedes asociar múltiples bibliotecas a un único agente. Por ejemplo, un asistente de soporte podría utilizar tanto la documentación del producto como los procedimientos internos. Aquí, las instrucciones son algo más que un simple añadido. Sin la directriz de limitar las respuestas a los documentos, el modelo rellenará los huecos con su conocimiento general y perderás la capacidad de distinguir qué proviene de tus archivos y qué procede de otra fuente. La tercera línea —indicar explícitamente cuándo falta información— es lo que convierte a un agente parlanchín en uno fiable.

Consultar los documentos

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="¿Cómo funciona el codificador de visión Pixtral 12B?"
)

for entry in response.outputs:
    if entry.type == "message.output":
        for chunk in entry.content:
            if chunk.type == "text":
                print(chunk.text)
            elif chunk.type == "tool_reference":
                print(f"  [Fuente] {chunk.title}")

Al igual que en la búsqueda web, la respuesta llega en fragmentos de dos tipos. Los fragmentos text contienen la respuesta escrita; los fragmentos tool_reference contienen la procedencia, donde el campo title guarda el nombre del documento fuente y el campo url proporciona la referencia interna dentro de dicho documento. Esta separación te permite mostrar la respuesta y, justo debajo, la lista de documentos que la han generado.

Esta trazabilidad no es solo decorativa. Un asesor que responda a un cliente basándose en un procedimiento interno debe poder especificar qué procedimiento está citando; un abogado que se apoye en un contrato debe poder rastrear dicho contrato. Sin citas, un sistema RAG produce afirmaciones inverificables.

Gestionar bibliotecas

# Listar bibliotecas
libraries = client.beta.libraries.list()
for lib in libraries.data:
    print(f"{lib.name} ({lib.id})")

# Listar documentos en una biblioteca
documents = client.beta.libraries.documents.list(library_id=library.id)
for doc in documents.data:
    print(f"{doc.name} — {doc.size} bytes")

# Eliminar un documento de la biblioteca
client.beta.libraries.documents.delete(
    library_id=library.id,
    document_id=document.id
)

# Eliminar la biblioteca
client.beta.libraries.delete(library_id=library.id)

Eliminar documentos es la operación que se pasa por alto con mayor frecuencia y la más costosa cuando se olvida. Una versión obsoleta de una lista de precios o de un procedimiento seguirá siendo citable por el agente indefinidamente, manteniendo toda la apariencia de legitimidad por el hecho de estar referenciada. Convierte la eliminación de un documento en un reflejo automático cada vez que publiques una nueva versión.

Del soporte interno al análisis de contratos

El soporte interno es el caso de uso más inmediato: los empleados formulan preguntas de RR. HH. en lenguaje natural en lugar de buscar manualmente en la intranet.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Soporte interno",
    instructions="Responde a las preguntas de los empleados utilizando la base de documentación de RR. HH.",
    tools=[{"type": "document_library", "library_ids": [rh_library.id]}]
)

El análisis de contratos cambia el paradigma: el agente no solo recupera, sino que examina. Aquí, las instrucciones describen una tarea, no solo un ámbito de aplicación.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Analista de contratos",
    instructions="""Analiza los contratos subidos.
- Identifica las cláusulas importantes
- Señala los riesgos potenciales
- Compara con los estándares del sector""",
    tools=[{"type": "document_library", "library_ids": [contrats_library.id]}]
)

Por último, una base de conocimientos de producto ilustra la combinación de herramientas: la documentación oficial tiene prioridad y la búsqueda web rellena los huecos cuando los documentos no cubren una pregunta.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Experto en producto",
    instructions="Responde a preguntas técnicas sobre nuestros productos basándote en la documentación oficial.",
    tools=[
        {"type": "document_library", "library_ids": [docs_library.id]},
        {"type": "web_search"}  # Alternativa si la documentación es insuficiente
    ]
)

Preparar las fuentes y aislar las bibliotecas

La calidad del RAG se determina antes incluso de llamar a la API. Un PDF estructurado con títulos, subtítulos y párrafos bien diferenciados se fragmenta y recupera mucho mejor que un escaneo aplanado o un documento donde toda la lógica reside en el diseño. A continuación, separa tus bibliotecas por dominio en lugar de crear un único contenedor general. Un agente conectado solo a la biblioteca legal no correrá el riesgo de citar una nota de RR. HH. para responder a una pregunta sobre un contrato. Estas dos decisiones —pulir la estructura de las fuentes y aislar las bibliotecas— impactan en el resultado final más que cualquier ajuste del modelo.

Puntos clave

  • document_library es un RAG integrado: no necesitas gestionar tu propia infraestructura vectorial
  • Crea bibliotecas temáticas y sube documentos mediante la API de Files
  • Las respuestas citan los pasajes relevantes utilizando fragmentos tool_reference
  • Puedes asociar múltiples bibliotecas a un único agente
  • Combínala con otras herramientas para obtener una cobertura completa