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 em sua resposta, você deve adicionar algo como “Sempre use citações em sua resposta, mesmo dentro de .”

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:

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 sentenças permitiria ao Claude citar uma única sentença ou encadear múltiplas sentenças 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 sentenças. Citar imagens de PDFs não é atualmente suportado.
    • Para documentos de texto simples: O conteúdo é fragmentado em sentenças 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 nos 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.
  • Os í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 sentenças. 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 sentenças 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 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 do documento como texto ou json stringificado.

​
Índices de citação

  • Os í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).
  • Os índices de caracteres são indexados em 0 com índices finais exclusivos.
  • Os números de página são indexados em 1 com números de página finais exclusivos.
  • Os í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 documentos. 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.

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
  • As 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. Os documentos podem ser fornecidos diretamente na mensagem (base64, texto ou URL) ou carregados via API Files e referenciados por file_id:

TipoMelhor paraFragmentaçãoFormato de citação
Texto simplesDocumentos de texto simples, prosaSentençaÍndices de caracteres (indexado em 0)
PDFArquivos PDF com conteúdo de textoSentençaNúmeros de página (indexado em 1)
Conteúdo personalizadoListas, transcrições, formatação especial, citações mais granularesNenhuma fragmentação adicionalÍndices de blocos (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 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": "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}
}

​
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 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.

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

​
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}
}

​
Estrutura de Resposta

Quando as citações estã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.