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

Implementar citas en Python

Lección 9 de 16 Actualizado el 3 de noviembre de 2026 Avanzado
En esta página
  1. El flujo completo de citas
  2. Definir el contrato del modelo en el mensaje de sistema
  3. Declarar la herramienta de búsqueda
  4. Devolver resultados en formato de referencia
  5. Separar texto de referencias
  6. Preparar la visualización en el frontend
  7. Puntos clave

Actualizado el 3 de noviembre de 2026 según la guía de Citas y referencias de Mistral: el resultado de la herramienta sigue el formato documentado: un objeto indexado por el número de fuente, sin campos type ni reference_id, y los reference_ids de la respuesta se resuelven mediante str(ref_id) dentro de dicho objeto. Fuente: Citas y referencias.

El flujo completo de citas

Ahora vas a montar un flujo RAG que cite sus fuentes, desde la primera llamada a la API hasta la estructura de datos que consume tu interfaz. Ten presente este principio: el modelo nunca recupera documentos por sí mismo. Indica que necesita una búsqueda, tú ejecutas esa búsqueda en tu propia base de datos y luego devuelves los fragmentos junto con sus identificadores. Este ida y vuelta genera una respuesta en la que cada afirmación permanece vinculada a un documento real.

En concreto, un ciclo completo requiere dos llamadas a chat.complete. La primera desencadena la llamada a la herramienta; la segunda genera la respuesta con citas una vez que las fuentes se han inyectado en el historial. Recorreremos este ciclo con un caso sencillo: un asistente de documentación interna al que se le preguntan las mejores prácticas para desplegar un LLM.

Definir el contrato del modelo en el mensaje de sistema

El mensaje de sistema establece el contrato: responde basándote en las fuentes proporcionadas, cita de forma sistemática y, sobre todo, admite cuando falta información en lugar de rellenar el hueco. Esta última instrucción marca la diferencia en producción, porque las respuestas tienden a desviarse en preguntas poco cubiertas por la base de documentación.

from mistralai.client import Mistral
import json

client = Mistral(api_key="your-api-key")

# Mensaje de sistema que fomenta las citas
system_message = {
    "role": "system",
    "content": (
        "Eres un asistente de documentación. "
        "Responde a las preguntas usando las fuentes proporcionadas. "
        "Cita tus fuentes de forma sistemática. "
        "Si la información no está en ninguna fuente, indícalo explícitamente."
    )
}

user_message = {
    "role": "user",
    "content": "¿Cuáles son las mejores prácticas para desplegar un LLM en producción?"
}

messages = [system_message, user_message]

Declarar la herramienta de búsqueda

La herramienta describe cómo es una búsqueda de documentos en tu sistema: aquí, una función sencilla search_documentation que toma una consulta de texto. La primera llamada no espera una respuesta escrita; espera que el modelo formule la consulta que considere relevante, ahorrándote escribir una capa de reformulación.

reference_tool = {
    "type": "function",
    "function": {
        "name": "search_documentation",
        "description": "Busca en la base de datos de documentación",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {
                    "type": "string",
                    "description": "Consulta de búsqueda"
                }
            },
            "required": ["query"]
        }
    }
}

# Primera llamada: el modelo solicita usar la herramienta
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=[reference_tool]
)

Devolver resultados en formato de referencia

Este es el paso estructural. Los resultados de tu motor de búsqueda vuelven en un ToolMessage cuyo contenido es el objeto de referencia de la lección anterior: cada fuente tiene un número ("0", "1"…), una URL, un título y los fragmentos seleccionados. Estos son los números que el modelo reutiliza para marcar sus citas y que tu frontend resolverá después en enlaces.

from mistralai.client.models import ToolMessage

# Resultados de la búsqueda de documentación, en formato de referencia de Mistral
references = {
    "0": {
        "url": "https://docs.example.com/deployment-guide",
        "title": "Guía de despliegue de LLM",
        "snippets": [[
            "Configura siempre límites de tasa para proteger el servicio.",
            "Monitoriza continuamente la latencia P99 y las tasas de error."
        ]],
        "description": None,
        "date": "2026-09-01",
        "source": "docs"
    },
    "1": {
        "url": "https://docs.example.com/security",
        "title": "Seguridad de aplicaciones de IA",
        "snippets": [[
            "Filtra las entradas de usuario para prevenir inyecciones.",
            "Nunca expongas claves de API en el lado del cliente."
        ]],
        "description": None,
        "date": "2026-08-15",
        "source": "docs"
    },
    "2": {
        "url": "https://docs.example.com/scaling",
        "title": "Escalabilidad y rendimiento",
        "snippets": [[
            "Usa caché semántico para reducir llamadas a la API.",
            "Dimensiona las instancias en función del tráfico pico."
        ]],
        "description": None,
        "date": "2026-07-20",
        "source": "docs"
    }
}

# Añade la llamada a la herramienta y la respuesta al historial
tool_call = response.choices[0].message.tool_calls[0]
messages.append(response.choices[0].message)

messages.append(
    ToolMessage(
        tool_call_id=tool_call.id,
        name="search_documentation",
        content=json.dumps(references, ensure_ascii=False)
    )
)

Ten en cuenta que el mensaje original del modelo se reinyecta en el historial antes del ToolMessage: sin este par llamada a herramienta / resultado de herramienta, la API rechaza la continuación. La segunda llamada ya no necesita las definiciones de herramienta, puesto que la búsqueda ya ha tenido lugar.

# Segunda llamada: el modelo genera una respuesta con citas
final_response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages
)

Separar texto de referencias

La respuesta con citas ya no es una simple cadena, sino una secuencia de fragmentos que alternan prosa y marcas de cita. El análisis implica recorrer esta secuencia y clasificar: los objetos TextChunk reconstruyen el texto legible, mientras que los objetos ReferenceChunk entregan los reference_ids realmente utilizados. Esta distinción te proporciona información valiosa: exactamente qué fuentes ha usado el modelo entre las que proporcionaste.

from mistralai.client.models import TextChunk, ReferenceChunk

def parse_cited_response(response):
    """Extrae texto y referencias de una respuesta con citas."""
    content_parts = response.choices[0].message.content
    text_parts = []
    cited_refs = set()

    for chunk in content_parts:
        if isinstance(chunk, TextChunk):
            text_parts.append(chunk.text)
        elif isinstance(chunk, ReferenceChunk):
            for ref_id in chunk.reference_ids:
                cited_refs.add(ref_id)

    return {
        "text": "".join(text_parts),
        "references_used": list(cited_refs)
    }

result = parse_cited_response(final_response)
print("=== Respuesta ===")
print(result["text"])
print("\n=== Fuentes citadas ===")
for ref_id in result["references_used"]:
    source = references[str(ref_id)]
    print(f"  - {source['title']} : {source['url']}")

Preparar la visualización en el frontend

Aplanar la respuesta a texto plano haría perder la posición de las citas y, por tanto, su valor. Es mejor mantener la secuencia y enriquecerla: resuelve cada ReferenceChunk frente a una tabla de referencias para llevar el título y la URL de cada fuente. Tu interfaz recibe así una lista ordenada de bloques que puede renderizar como enlaces clicables, tooltips o números de cita interactivos, sin tener que reinterpretar nunca el texto.

def format_for_frontend(response, reference_map):
    """Formatea la respuesta con citas para el frontend."""
    content_parts = response.choices[0].message.content
    formatted = []

    for chunk in content_parts:
        if isinstance(chunk, TextChunk):
            formatted.append({
                "type": "text",
                "content": chunk.text
            })
        elif isinstance(chunk, ReferenceChunk):
            refs = []
            for ref_id in chunk.reference_ids:
                source = reference_map.get(str(ref_id))
                if source:
                    refs.append({
                        "id": ref_id,
                        "title": source["title"],
                        "url": source["url"]
                    })
            formatted.append({
                "type": "citation",
                "references": refs
            })

    return formatted

Antes de abrir este flujo a toda tu base de documentación, ejecútalo con solo tres a cinco fuentes, como en el ejemplo anterior. Verás de inmediato si el modelo cita en el lugar correcto, si aprovecha varios documentos o si se aferra sistemáticamente al primero, lo que te permitirá corregir el mensaje de sistema antes de que el comportamiento se pierda en el volumen.

Puntos clave

  • El flujo sigue un proceso de dos llamadas: llamada a herramienta y luego respuesta con citas
  • Las referencias se pasan mediante ToolMessage, en un objeto indexado por el número de fuente ("0", "1"…)
  • La respuesta contiene una mezcla de TextChunk y ReferenceChunk que hay que analizar
  • Estructura la salida para que tu frontend pueda mostrar citas interactivas
  • Prueba con 3–5 fuentes para validar el comportamiento antes de pasar a producción