Citações

O Claude pode fornecer citações detalhadas ao responder perguntas sobre documentos, ajudando você a rastrear e verificar as fontes por trás de cada resposta.

Todos os modelos ativos oferecem suporte a citações.

O exemplo a seguir mostra como habilitar citações em um documento de texto simples com a Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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)



Como as citações funcionam

Integre citações com o Claude seguindo estas etapas:



Conteúdo citável versus não citável

• O texto encontrado dentro do conteúdo source de um documento pode ser citado.
• title e context são campos opcionais que são passados para o modelo, mas não são usados como conteúdo citável.
• title tem comprimento limitado, então o campo context é útil para armazenar metadados do documento como texto ou JSON em formato de string.



Índices de citação

• Índices de documentos são indexados a partir de 0 com base na lista de todos os blocos de conteúdo de documento na requisição (abrangendo todas as mensagens).
• Índices de caracteres são indexados a partir de 0 com índices finais exclusivos.
• Números de página são indexados a partir de 1 com números de página finais exclusivos.
• Índices de blocos de conteúdo são indexados a partir de 0 com índices finais exclusivos a partir da lista content fornecida no documento de conteúdo personalizado.



Custos de tokens

• Habilitar citações gera um leve aumento nos tokens de entrada devido a adições ao prompt do sistema e à divisão de documentos.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Internamente, o modelo gera citações em um formato padronizado que é então analisado em texto citado e índices de localização de documentos. O campo cited_text é fornecido por conveniência e não conta para os tokens de saída.
• Quando passado de volta em turnos subsequentes da conversa, cited_text também não é contado para os tokens de entrada.



Compatibilidade de recursos

As citações funcionam em conjunto com outros recursos da API, incluindo cache de prompt, contagem de tokens e processamento em lote.



Usando cache de prompt com citações

Citações e cache de prompt podem ser usados juntos de forma eficaz.

Os blocos de citação gerados nas respostas não podem ser armazenados em cache diretamente, mas os documentos de origem que eles referenciam podem ser armazenados em cache. Para otimizar o desempenho, aplique cache_control aos seus blocos de conteúdo de documento de nível superior.

client = anthropic.Anthropic()

# Conteúdo de documento longo (por exemplo, documentação 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",
    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)

Neste exemplo:

• O conteúdo do documento é armazenado em cache usando cache_control no bloco de documento.
• As citações estão habilitadas no documento.
• O Claude pode gerar respostas com citações enquanto se beneficia do conteúdo do documento em cache.
• Requisições subsequentes usando o mesmo documento se beneficiam do conteúdo em cache.



Tipos de documentos



Escolhendo um tipo de documento

Três tipos de documentos são suportados para citações. Os documentos podem ser fornecidos diretamente na mensagem (base64, texto ou URL) ou enviados por meio da Files API e referenciados por file_id:



Documentos de texto simples

Documentos de texto simples são automaticamente divididos em sentenças. Você pode fornecê-los inline ou por referência com seu file_id:

{
  "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

Documentos PDF podem ser fornecidos como dados codificados em base64, uma URL ou por file_id. O texto do PDF é extraído e dividido em sentenças. Como citações de imagens ainda não são suportadas, PDFs que são digitalizações de documentos e não contêm texto extraível não são citáveis.

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",
    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 conteúdo personalizado

Documentos de conteúdo personalizado dão a você controle sobre a granularidade das citações. Nenhuma divisão adicional é feita e os chunks são fornecidos ao modelo de acordo com os blocos de conteúdo fornecidos.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-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)



Estrutura da resposta

Quando as citações estão habilitadas, as respostas incluem vários blocos de texto com citações:

{
    "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,
                }
            ],
        },
    ]
}



Suporte a streaming

Para respostas em streaming, as citações chegam como um tipo de delta citations_delta dentro de eventos content_block_delta. Cada delta contém uma única citação a ser adicionada à lista citations no bloco de conteúdo text atual.



Próximos passos