Claude Platform Docs
MensajesCapacidades del modelo

Citas

Fundamenta las respuestas de Claude en tus documentos fuente. Las citas devuelven los pasajes exactos que respaldan cada afirmación, para que puedas verificar las respuestas y mostrar las fuentes a tus usuarios.

Claude puede proporcionar citas detalladas al responder preguntas sobre documentos, ayudándote a rastrear y verificar las fuentes detrás de cada respuesta.

Todos los modelos activos admiten citas.

El siguiente ejemplo muestra cómo habilitar citas en un documento de texto plano con la API de Mensajes:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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 en estos pasos:

  1. Proporciona documento(s) y habilita las citas

    • Incluye documentos en cualquiera de los formatos admitidos: documentos PDF, texto plano o contenido personalizado.
    • Establece citations.enabled=true en cada uno de tus documentos. Actualmente, las citas deben habilitarse en todos o en ninguno de los documentos dentro de una solicitud.
    • Actualmente solo se admiten citas de texto. Las citas de imágenes aún no son posibles.

  2. Los documentos se procesan

    • El contenido de los documentos se “fragmenta” para definir la granularidad mínima de las posibles citas. Por ejemplo, la fragmentación por oraciones permite que Claude cite una sola oración o encadene varias oraciones consecutivas para citar un párrafo o un pasaje más largo.
      • Para PDFs: El texto se extrae como se describe en Soporte de PDF y el contenido se fragmenta en oraciones. Actualmente no se admite citar imágenes de PDFs.
      • Para documentos de texto plano: El contenido se fragmenta en oraciones que pueden citarse.
      • Para documentos de contenido personalizado: Los bloques de contenido que proporcionas se usan tal cual y no se realiza ninguna fragmentación adicional.

  3. Claude proporciona una respuesta con citas

    • Las respuestas ahora pueden incluir varios bloques de texto, donde cada bloque de texto puede contener una afirmación que Claude está haciendo y una lista de citas que respaldan dicha afirmación.
    • Las citas hacen referencia a ubicaciones específicas en los documentos fuente. El formato de estas citas depende del tipo de documento que se esté citando.
      • Para PDFs: Las citas incluyen el rango de números de página (indexado desde 1).
      • Para documentos de texto plano: Las citas incluyen el rango de índices de caracteres (indexado desde 0).
      • Para documentos de contenido personalizado: Las citas incluyen el rango de índices de bloques de contenido (indexado desde 0) correspondiente a la lista de contenido original proporcionada.
    • Los índices de documentos se proporcionan para indicar la fuente de referencia y están indexados desde 0 según la lista de todos los documentos en tu solicitud original.

Contenido citable versus no citable

  • El texto que se encuentra dentro del contenido source de un documento puede citarse.
  • title y context son campos opcionales que se pasan al modelo pero no se usan para el contenido citado.
  • title tiene una longitud limitada, por lo que el campo context es útil para almacenar metadatos del documento como texto o JSON en formato de 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 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 las citas en un formato estandarizado, y esas citas luego se analizan en texto citado e índices de ubicación en el 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 almacenamiento en caché de prompts, conteo de tokens y procesamiento por lotes.

Obtener datos estructurados con citas

Para obtener una cita para cada valor extraído, pide a Claude que responda con una línea por campo. Luego, analiza las líneas para convertirlas en datos estructurados en tu código.

Evita los prompts de usuario o las indicaciones del sistema que pidan solo JSON, como “Devuelve solo un objeto JSON, sin ningún otro texto”. Una solicitud con un prompt así se completa correctamente, pero la respuesta podría contener pocas citas o ninguna.

El siguiente prompt solicita dos campos del documento de texto plano del ejemplo que aparece al principio de esta página. Envíalo en lugar de la pregunta de ese ejemplo:

Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

En la siguiente respuesta, cada valor tiene sus propias citas:

{
  "content": [
    { "type": "text", "text": "grass_color: " },
    {
      "type": "text",
      "text": "green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": "\nsky_color: " },
    {
      "type": "text",
      "text": "blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    }
  ]
}

Para analizar la respuesta, sigue estos pasos:

  1. Lee los bloques text en orden y agrega el texto de cada bloque a la línea actual. Comienza una nueva línea en cada carácter de salto de línea.
  2. Asocia las citations de cada bloque a cada línea que contenga parte de su texto. Un bloque citado puede contener solo el valor, como en este ejemplo, o una línea completa.
  3. Omite las líneas que no tengan dos puntos. Divide cada línea restante en el primer signo de dos puntos en un nombre de campo y un valor, y elimina los espacios iniciales y finales de ambos. Omite las líneas cuyo nombre no sea uno de tus campos, como una nota de cierre.
  4. Verifica que cada campo tenga un valor y al menos una cita. La API no garantiza ninguno de los dos.

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.

client = anthropic.Anthropic()

# Contenido de documento extenso (por ejemplo, documentación técnica)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document,
                    },
                    "citations": {"enabled": True},
                    "cache_control": {
                        "type": "ephemeral"
                    },  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

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 usan el mismo documento se benefician 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 API de Archivos y referenciarse mediante file_id:

TipoMejor paraFragmentaciónFormato de cita
Texto planoDocumentos de texto simples, prosaOraciónÍndices de caracteres (indexado desde 0)
PDFArchivos PDF con contenido de textoOraciónNúmeros de página (indexado desde 1)
Contenido personalizadoListas, transcripciones, formato especial, citas más granularesSin fragmentación adicionalÍndices de bloques (indexado desde 0)

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:

El ejemplo introductorio en la parte superior de esta página muestra una solicitud completa de texto plano en cada SDK. El bloque del documento usa una fuente text:

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

Documentos PDF

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

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

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.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "content",
                        "content": [
                            {"type": "text", "text": "First chunk"},
                            {"type": "text", "text": "Second chunk"},
                        ],
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

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, las citas llegan como un tipo de delta citations_delta dentro de los eventos content_block_delta. Cada delta contiene una sola cita para agregar a la lista citations en el bloque de contenido text actual.

Próximos pasos

Mensajes en streaming

Aprende el flujo de eventos y los otros tipos de delta de bloques de contenido que llegan junto con citations_delta.

Resultados de búsqueda

Pasa los resultados de búsqueda de tu pipeline RAG como bloques de contenido de primera clase con soporte de citas integrado.

Soporte de PDF

Aprende cómo Claude extrae texto de los PDFs y cómo las citas basadas en páginas se asignan de vuelta a tus archivos fuente.

API de Archivos

Carga documentos una vez y referéncialos mediante file_id en múltiples solicitudes de citas.

Disponibilidad

Citas
API
  • Messages API
  • Managed Agents No compatible
Modelos
  • Todos los modelos

Manejo de datos

Descripción general del manejo de datos

Endpoints aplicables

  • /v1/messages
Retención de datos ceroElegible

Excluye Modelos cubiertos

HIPAAElegible

¿Te resultó útil esta página?