Citações

Claude é capaz de fornecer citações detalhadas ao responder perguntas sobre documentos, ajudando você a rastrear e verificar fontes de informações em respostas.

Todos os modelos ativos suportam citações, com exceção do Haiku 3.

Aqui está um exemplo de como usar citações com a API Messages:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 Claude nestas etapas:

Conteúdo citável vs 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 serão passados para o modelo mas não usados para conteúdo citado.
• title é limitado em comprimento, então você pode achar o campo context útil para armazenar qualquer metadado de documento como texto ou json stringificado.

Índices de citação

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

Custos de token

• Ativar citações incorre em um ligeiro aumento em tokens de entrada devido a adições de prompt do sistema e chunking de documento.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Nos bastidores, o modelo está gerando citações em um formato padronizado que são então analisadas em texto citado e índices de localização de documento. O campo cited_text é fornecido por conveniência e não conta para tokens de saída.
• Quando passado novamente em turnos de conversa subsequentes, cited_text também não é contado para tokens de entrada.

Compatibilidade de recursos

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

Usando Cache de Prompts com Citações

Citações e cache de prompts podem ser usados juntos efetivamente.

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

Neste exemplo:

• O conteúdo do documento é armazenado em cache usando cache_control no bloco de documento
• As citações são ativadas no documento
• Claude pode gerar respostas com citações enquanto se beneficia do conteúdo do documento armazenado em cache
• Solicitações subsequentes usando o mesmo documento se beneficiarão do conteúdo armazenado em cache

Tipos de Documento

Escolhendo um tipo de documento

Três tipos de documento são suportados para citações. Os documentos podem ser fornecidos diretamente na mensagem (base64, texto ou URL) ou carregados via API de Arquivos 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:

Documentos PDF

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

Documentos de conteúdo personalizado

Documentos de conteúdo personalizado lhe dão controle sobre a granularidade de citação. Nenhum chunking adicional é feito e os chunks são fornecidos ao modelo de acordo com os blocos de conteúdo fornecidos.

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

Estrutura de Resposta

Quando as citações são ativadas, 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 de streaming, um tipo citations_delta é incluído que contém uma única citação a ser adicionada à lista citations no bloco de conteúdo text atual.