Citas

Claude es capaz de proporcionar citas detalladas al responder preguntas sobre documentos, ayudándote a rastrear y verificar las fuentes de información en las respuestas.

Todos los modelos activos admiten citas, con la excepción de Haiku 3.

Aquí tienes un ejemplo de cómo usar citas con la API de Messages:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "The grass is green. The sky is blue.",
                    },
                    "title": "My Document",
                    "context": "This is a trustworthy document.",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "What color is the grass and sky?"},
            ],
        }
    ],
)
print(response)



Cómo funcionan las citas

Integra las citas con Claude siguiendo estos pasos:



Contenido citable vs. no citable

• El texto que se encuentra dentro del contenido source de un documento puede citarse.
• title y context son campos opcionales que se pasarán al modelo pero no se usarán como contenido citable.
• title tiene una longitud limitada, por lo que puede resultarte útil el campo context para almacenar cualquier metadato del documento como texto o JSON convertido a cadena.



Índices de citas

• Los índices de documentos están indexados desde 0 a partir de la lista de todos los bloques de contenido de documentos en la solicitud (abarcando todos los mensajes).
• Los índices de caracteres están indexados desde 0 con índices finales exclusivos.
• Los números de página están indexados desde 1 con números de página finales exclusivos.
• Los índices de bloques de contenido están indexados desde 0 con índices finales exclusivos a partir de la lista content proporcionada en el documento de contenido personalizado.



Costos de tokens

• Habilitar las citas genera un ligero aumento en los tokens de entrada debido a las adiciones a la indicación del sistema y la fragmentación de documentos.
• Sin embargo, la función de citas es muy eficiente con los tokens de salida. Internamente, el modelo genera citas en un formato estandarizado que luego se analizan para obtener el texto citado y los índices de ubicación del documento. El campo cited_text se proporciona por conveniencia y no cuenta para los tokens de salida.
• Cuando se devuelve en turnos de conversación posteriores, cited_text tampoco cuenta para los tokens de entrada.



Compatibilidad de funciones

Las citas funcionan en conjunto con otras funciones de la API, incluyendo el almacenamiento en caché de prompts, el conteo de tokens y el procesamiento por lotes.



Uso del almacenamiento en caché de prompts con citas

Las citas y el almacenamiento en caché de prompts pueden usarse juntos de manera efectiva.

Los bloques de citas generados en las respuestas no pueden almacenarse en caché directamente, pero los documentos fuente a los que hacen referencia sí pueden almacenarse en caché. Para optimizar el rendimiento, aplica cache_control a tus bloques de contenido de documentos de nivel superior.

En este ejemplo:

• El contenido del documento se almacena en caché usando cache_control en el bloque del documento
• Las citas están habilitadas en el documento
• Claude puede generar respuestas con citas mientras se beneficia del contenido del documento almacenado en caché
• Las solicitudes posteriores que usen el mismo documento se beneficiarán del contenido almacenado en caché



Tipos de documentos



Elegir un tipo de documento

Se admiten tres tipos de documentos para las citas. Los documentos pueden proporcionarse directamente en el mensaje (base64, texto o URL) o cargarse a través de la Files API y referenciarse mediante file_id:



Documentos de texto plano

Los documentos de texto plano se fragmentan automáticamente en oraciones. Puedes proporcionarlos en línea o por referencia con su file_id:



Documentos PDF

Los documentos PDF pueden proporcionarse como datos codificados en base64, una URL o mediante file_id. El texto del PDF se extrae y se fragmenta en oraciones. Como aún no se admiten las citas de imágenes, los PDFs que son escaneos de documentos y no contienen texto extraíble no podrán citarse.



Documentos de contenido personalizado

Los documentos de contenido personalizado te dan control sobre la granularidad de las citas. No se realiza ninguna fragmentación adicional y los fragmentos se proporcionan al modelo según los bloques de contenido proporcionados.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "citations": {"enabled": True},
}



Estructura de la respuesta

Cuando las citas están habilitadas, las respuestas incluyen múltiples bloques de texto con citas:

{
    "content": [
        {"type": "text", "text": "According to the document, "},
        {
            "type": "text",
            "text": "the grass is green",
            "citations": [
                {
                    "type": "char_location",
                    "cited_text": "The grass is green.",
                    "document_index": 0,
                    "document_title": "Example Document",
                    "start_char_index": 0,
                    "end_char_index": 20,
                }
            ],
        },
        {"type": "text", "text": " and "},
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [
                {
                    "type": "char_location",
                    "cited_text": "The sky is blue.",
                    "document_index": 0,
                    "document_title": "Example Document",
                    "start_char_index": 20,
                    "end_char_index": 36,
                }
            ],
        },
        {
            "type": "text",
            "text": ". Information from page 5 states that ",
        },
        {
            "type": "text",
            "text": "water is essential",
            "citations": [
                {
                    "type": "page_location",
                    "cited_text": "Water is essential for life.",
                    "document_index": 1,
                    "document_title": "PDF Document",
                    "start_page_number": 5,
                    "end_page_number": 6,
                }
            ],
        },
        {
            "type": "text",
            "text": ". The custom document mentions ",
        },
        {
            "type": "text",
            "text": "important findings",
            "citations": [
                {
                    "type": "content_block_location",
                    "cited_text": "These are important findings.",
                    "document_index": 2,
                    "document_title": "Custom Content Document",
                    "start_block_index": 0,
                    "end_block_index": 1,
                }
            ],
        },
    ]
}



Soporte de streaming

Para respuestas en streaming, se incluye un tipo citations_delta que contiene una sola cita que debe agregarse a la lista citations en el bloque de contenido text actual.