Citações

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

O recurso de citações está atualmente disponível no Claude Opus 4, Claude Sonnet 4, Claude Sonnet 3.7, Claude Sonnet 3.5 (novo) e Haiku 3.5.

Citações com Claude Sonnet 3.7

Claude Sonnet 3.7 pode ser menos propenso a fazer citações em comparação com outros modelos Claude sem instruções mais explícitas do usuário. Ao usar citações com Claude Sonnet 3.7, recomendamos incluir instruções adicionais na mensagem do user, como "Use citações para apoiar sua resposta." por exemplo.

Também observamos que quando o modelo é solicitado a estruturar sua resposta, é improvável que use citações, a menos que seja explicitamente instruído a usar citações dentro desse formato. Por exemplo, se o modelo for solicitado a usar tags <result> em sua resposta, você deve adicionar algo como "Sempre use citações em sua resposta, mesmo dentro de tags <result>."

Por favor, compartilhe seu feedback e sugestões sobre o recurso de citações usando este formulário.

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

Shell

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-20250514",
    "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?"
          }
        ]
      }
    ]
  }'

Comparação com abordagens baseadas em prompt

Em comparação com soluções de citações baseadas em prompt, o recurso de citações tem as seguintes vantagens:

• Economia de custos: Se sua abordagem baseada em prompt pede ao Claude para produzir citações diretas, você pode ver economia de custos devido ao fato de que cited_text não conta para seus tokens de saída.
• Melhor confiabilidade de citação: Como analisamos citações nos respectivos formatos de resposta mencionados acima e extraímos cited_text, as citações são garantidas de conter ponteiros válidos para os documentos fornecidos.
• Qualidade de citação aprimorada: Em nossas avaliações, descobrimos que o recurso de citações é significativamente mais propenso a citar as citações mais relevantes de documentos em comparação com abordagens puramente baseadas em prompt.

---

Como as citações funcionam

Integre citações com Claude nestas etapas:

1. Forneça documento(s) e habilite citações

   • Inclua documentos em qualquer um dos formatos suportados: PDFs, texto simples, ou documentos de conteúdo personalizado
   • Defina citations.enabled=true em cada um de seus documentos. Atualmente, as citações devem ser habilitadas em todos ou nenhum dos documentos dentro de uma solicitação.
   • Note que apenas citações de texto são atualmente suportadas e citações de imagem ainda não são possíveis.
2. Documentos são processados

   • O conteúdo dos documentos é “fragmentado” para definir a granularidade mínima de possíveis citações. Por exemplo, fragmentação de frases permitiria ao Claude citar uma única frase ou encadear múltiplas frases consecutivas para citar um parágrafo (ou mais longo)!
     • Para PDFs: O texto é extraído conforme descrito em Suporte a PDF e o conteúdo é fragmentado em frases. Citar imagens de PDFs não é atualmente suportado.
     • Para documentos de texto simples: O conteúdo é fragmentado em frases que podem ser citadas.
     • Para documentos de conteúdo personalizado: Seus blocos de conteúdo fornecidos são usados como estão e nenhuma fragmentação adicional é feita.
3. Claude fornece resposta citada

   • As respostas podem agora incluir múltiplos blocos de texto onde cada bloco de texto pode conter uma afirmação que Claude está fazendo e uma lista de citações que apoiam a afirmação.
   • As citações referenciam localizações específicas em documentos fonte. O formato dessas citações depende do tipo de documento sendo citado.
     • Para PDFs: as citações incluirão o intervalo de números de página (indexado em 1).
     • Para documentos de texto simples: As citações incluirão o intervalo de índices de caracteres (indexado em 0).
     • Para documentos de conteúdo personalizado: As citações incluirão o intervalo de índices de blocos de conteúdo (indexado em 0) correspondente à lista de conteúdo original fornecida.
   • Índices de documentos são fornecidos para indicar a fonte de referência e são indexados em 0 de acordo com a lista de todos os documentos em sua solicitação original.

Fragmentação automática vs conteúdo personalizado

Por padrão, documentos de texto simples e PDF são automaticamente fragmentados em frases. Se você precisar de mais controle sobre a granularidade da citação (por exemplo, para marcadores ou transcrições), use documentos de conteúdo personalizado em vez disso. Veja Tipos de Documento para mais detalhes.

Por exemplo, se você quiser que Claude seja capaz de citar frases específicas de seus fragmentos RAG, você deve colocar cada fragmento RAG em um documento de texto simples. Caso contrário, se você não quiser que nenhuma fragmentação adicional seja feita, ou se você quiser personalizar qualquer fragmentação adicional, você pode colocar fragmentos RAG em documento(s) de conteúdo personalizado.

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

• 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 quaisquer metadados de documento como texto ou json stringificado.

Índices de citação

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

Custos de token

• Habilitar citações incorre em um ligeiro aumento nos tokens de entrada devido a adições de prompt do sistema e fragmentação de documentos.
• No entanto, o recurso de citações é muito eficiente com tokens de saída. Por baixo dos panos, o modelo está produzindo 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 de volta em turnos de conversa subsequentes, cited_text também não é contado para tokens de entrada.

Compatibilidade de recursos

Citações funciona 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 efetivamente.

Os blocos de citação gerados nas respostas não podem ser armazenados em cache diretamente, mas os documentos fonte 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.

Python

import anthropic

client = anthropic.Anthropic()

# Conteúdo de documento longo (por exemplo, documentação técnica)
long_document = "Este é um documento muito longo com milhares de palavras..." + " ... " * 1000  # Comprimento mínimo armazenável em cache

response = client.messages.create(
    model="claude-opus-4-20250514",
    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"}  # Armazenar o conteúdo do documento em cache
                },
                {
                    "type": "text",
                    "text": "O que este documento diz sobre recursos da API?"
                }
            ]
        }
    ]
)

Neste exemplo:

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

Tipos de Documento

Escolhendo um tipo de documento

Suportamos três tipos de documento para citações. Documentos podem ser fornecidos diretamente na mensagem (base64, texto ou URL) ou carregados via API Files e referenciados por file_id:

Tipo	Melhor para	Fragmentação	Formato de citação
Texto simples	Documentos de texto simples, prosa	Frase	Índices de caracteres (indexado em 0)
PDF	Arquivos PDF com conteúdo de texto	Frase	Números de página (indexado em 1)
Conteúdo personalizado	Listas, transcrições, formatação especial, citações mais granulares	Nenhuma fragmentação adicional	Índices de bloco (indexado em 0)

Arquivos .csv, .xlsx, .docx, .md e .txt não são suportados como blocos de documento. Converta-os para texto simples e inclua diretamente no conteúdo da mensagem. Veja Trabalhando com outros formatos de arquivo.

Documentos de texto simples

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

Texto inline

{
    "type": "document",
    "source": {
        "type": "text",
        "media_type": "text/plain",
        "data": "Conteúdo de texto simples..."
    },
    "title": "Título do Documento", # opcional
    "context": "Contexto sobre o documento que não será citado", # opcional
    "citations": {"enabled": True}
}

Exemplo de citação de texto simples

{
    "type": "char_location",
    "cited_text": "O texto exato sendo citado", # não conta para tokens de saída
    "document_index": 0,
    "document_title": "Título do Documento",
    "start_char_index": 0,    # indexado em 0
    "end_char_index": 50      # exclusivo
}

Documentos PDF

Documentos PDF podem ser fornecidos como dados codificados em base64 ou por file_id. O texto do PDF é extraído e fragmentado em frases. 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.

Base64

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data
    },
    "title": "Título do Documento", # opcional
    "context": "Contexto sobre o documento que não será citado", # opcional
    "citations": {"enabled": True}
}

Exemplo de citação PDF

{
    "type": "page_location",
    "cited_text": "O texto exato sendo citado", # não conta para tokens de saída
    "document_index": 0,     
    "document_title": "Título do Documento", 
    "start_page_number": 1,  # indexado em 1
    "end_page_number": 2     # exclusivo
}

Documentos de conteúdo personalizado

Documentos de conteúdo personalizado dão a você controle sobre a granularidade da citação. Nenhuma fragmentação adicional é feita e os fragmentos são fornecidos ao modelo de acordo com os blocos de conteúdo fornecidos.

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "Primeiro fragmento"},
            {"type": "text", "text": "Segundo fragmento"}
        ]
    },
    "title": "Título do Documento", # opcional
    "context": "Contexto sobre o documento que não será citado", # opcional
    "citations": {"enabled": True}
}

Exemplo de citação

{
    "type": "content_block_location",
    "cited_text": "O texto exato sendo citado", # não conta para tokens de saída
    "document_index": 0,
    "document_title": "Título do Documento",
    "start_block_index": 0,   # indexado em 0
    "end_block_index": 1      # exclusivo
}

---

Estrutura de Resposta

Quando citações são habilitadas, as respostas incluem múltiplos blocos de texto com citações:

{
    "content": [
        {
            "type": "text",
            "text": "De acordo com o documento, "
        },
        {
            "type": "text",
            "text": "a grama é verde",
            "citations": [{
                "type": "char_location",
                "cited_text": "A grama é verde.",
                "document_index": 0,
                "document_title": "Documento de Exemplo",
                "start_char_index": 0,
                "end_char_index": 20
            }]
        },
        {
            "type": "text",
            "text": " e "
        },
        {
            "type": "text",
            "text": "o céu é azul",
            "citations": [{
                "type": "char_location",
                "cited_text": "O céu é azul.",
                "document_index": 0,
                "document_title": "Documento de Exemplo",
                "start_char_index": 20,
                "end_char_index": 36
            }]
        },
        {
            "type": "text",
            "text": ". Informações da página 5 afirmam que ",
        },
        {
            "type": "text",
            "text": "a água é essencial",
            "citations": [{
                "type": "page_location",
                "cited_text": "A água é essencial para a vida.",
                "document_index": 1,
                "document_title": "Documento PDF",
                "start_page_number": 5,
                "end_page_number": 6
            }]
        },
        {
            "type": "text",
            "text": ". O documento personalizado menciona ",
        },
        {
            "type": "text",
            "text": "descobertas importantes",
            "citations": [{
                "type": "content_block_location",
                "cited_text":  "Estas são descobertas importantes.",
                "document_index": 2,
                "document_title": "Documento de Conteúdo Personalizado",
                "start_block_index": 0,
                "end_block_index": 1
            }]
        }
    ]
}

Suporte a Streaming

Para respostas de streaming, adicionamos um tipo citations_delta que contém uma única citação a ser adicionada à lista citations no bloco de conteúdo text atual.

Exemplo de eventos de streaming

event: message_start
data: {"type": "message_start", ...}

event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, 
       "delta": {"type": "text_delta", "text": "De acordo com..."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "citations_delta", 
                 "citation": {
                     "type": "char_location",
                     "cited_text": "...",
                     "document_index": 0,
                     ...
                 }}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_stop
data: {"type": "message_stop"}