MensagensCapacidades do modelo

Citações

Fundamente as respostas do Claude em seus documentos de origem. As citações retornam as passagens exatas que sustentam cada afirmação, para que você possa verificar as respostas e apresentar as fontes aos seus usuários.

Este recurso é elegível para Zero Data Retention (ZDR). Quando sua organização possui um acordo de ZDR, os dados enviados por meio deste recurso não são armazenados após a resposta da API ser retornada.

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, com exceção do Claude Haiku 3.

Compartilhe seu feedback e sugestões sobre o recurso de citações usando o formulário de feedback de 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-4-8",
    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)

Comparação com abordagens baseadas em prompt

Em comparação com instruir o Claude via prompt a citar fontes, o recurso de citações oferece as seguintes vantagens:

Economia de custos: Se sua abordagem baseada em prompt pede ao Claude para gerar citações diretas, você pode observar economia de custos porque cited_text não conta para seus tokens de saída.
Melhor confiabilidade das citações: Como a API analisa as citações nos formatos de resposta descritos nas seções a seguir e extrai cited_text diretamente, é garantido que as citações contenham ponteiros válidos para os documentos fornecidos.
Melhor qualidade das citações: Nas avaliações da Anthropic, o recurso de citações tem probabilidade significativamente maior de citar os trechos mais relevantes dos documentos do que abordagens puramente baseadas em prompt.

Como as citações funcionam

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

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 dos seus documentos. Atualmente, as citações devem ser habilitadas em todos ou em nenhum dos documentos dentro de uma requisição.
- Apenas citações de texto são suportadas atualmente. Citações de imagens ainda não são possíveis.
Os documentos são processados
- O conteúdo dos documentos é dividido em "chunks" (fragmentos) para definir a granularidade mínima das citações possíveis. Por exemplo, a divisão por sentenças permite que o Claude cite uma única sentença ou encadeie várias sentenças consecutivas para citar um parágrafo ou uma passagem mais longa.
  - Para PDFs: O texto é extraído conforme descrito em Suporte a PDF e o conteúdo é dividido em sentenças. Citar imagens de PDFs não é suportado atualmente.
  - Para documentos de texto simples: O conteúdo é dividido em sentenças que podem ser citadas.
  - Para documentos de conteúdo personalizado: Os blocos de conteúdo que você fornece são usados como estão e nenhuma divisão adicional é feita.
O Claude fornece uma resposta com citações
- As respostas agora podem incluir vários blocos de texto, onde cada bloco de texto pode conter uma afirmação que o Claude está fazendo e uma lista de citações que sustentam essa afirmação.
- As citações referenciam localizações específicas nos documentos de origem. O formato dessas citações depende do tipo de documento que está sendo citado.
  - Para PDFs: As citações incluem o intervalo de números de página (indexado a partir de 1).
  - Para documentos de texto simples: As citações incluem o intervalo de índices de caracteres (indexado a partir de 0).
  - Para documentos de conteúdo personalizado: As citações incluem o intervalo de índices de blocos de conteúdo (indexado a partir de 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 a partir de 0 de acordo com a lista de todos os documentos na sua requisição original.

Divisão automática vs conteúdo personalizado

Por padrão, documentos de texto simples e PDF são automaticamente divididos em sentenças. Se você precisar de mais controle sobre a granularidade das citações (por exemplo, para listas com marcadores ou transcrições), use documentos de conteúdo personalizado. Consulte Tipos de documentos para mais detalhes.

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

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

Os í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).
Os índices de caracteres são indexados a partir de 0 com índices finais exclusivos.
Os números de página são indexados a partir de 1 com números de página finais exclusivos.
Os í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 do documento. O campo cited_text é fornecido por conveniência e não conta para os tokens de saída.
Quando passado de volta em turnos de conversa subsequentes, 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.

Citações e saídas estruturadas são incompatíveis

Citações não podem ser usadas junto com saídas estruturadas. Se você habilitar citações em qualquer documento fornecido pelo usuário (blocos document ou blocos search_result) e também incluir o parâmetro output_config.format (ou o parâmetro obsoleto output_format), a API retorna um erro 400.

Isso ocorre porque as citações exigem a intercalação de blocos de citação com a saída de texto, o que é incompatível com as restrições estritas de esquema JSON das saídas estruturadas.

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-4-8",
    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 do documento.
As citações sã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 através da Files API e referenciados por file_id:

Tipo	Melhor para	Divisão em chunks	Formato de citação
Texto simples	Documentos de texto simples, prosa	Sentença	Índices de caracteres (indexados a partir de 0)
PDF	Arquivos PDF com conteúdo de texto	Sentença	Números de página (indexados a partir de 1)
Conteúdo personalizado	Listas, transcrições, formatação especial, citações mais granulares	Sem divisão adicional	Índices de blocos (indexados a partir de 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. Consulte Trabalhando com outros formatos de arquivo.

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, 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 serão citáveis.

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-4-8",
    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

Mensagens em streaming

Trate o tipo de delta citations_delta junto com os deltas de texto para renderizar respostas citadas à medida que são transmitidas.

Resultados de busca

Passe resultados de busca do seu pipeline de RAG como blocos de conteúdo de primeira classe com suporte integrado a citações.

Suporte a PDF

Saiba como o Claude extrai texto de PDFs e como as citações baseadas em páginas são mapeadas de volta para seus arquivos de origem.

Files API

Faça upload de documentos uma vez e referencie-os por file_id em várias requisições de citação.

Was this page helpful?

MensagensCapacidades do modelo

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, com exceção do Claude Haiku 3.

Compartilhe seu feedback e sugestões sobre o recurso de citações usando o formulário de feedback de 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-4-8",
    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)

Comparação com abordagens baseadas em prompt

Em comparação com instruir o Claude via prompt a citar fontes, o recurso de citações oferece as seguintes vantagens:

Economia de custos: Se sua abordagem baseada em prompt pede ao Claude para gerar citações diretas, você pode observar economia de custos porque cited_text não conta para seus tokens de saída.
Melhor confiabilidade das citações: Como a API analisa as citações nos formatos de resposta descritos nas seções a seguir e extrai cited_text diretamente, é garantido que as citações contenham ponteiros válidos para os documentos fornecidos.
Melhor qualidade das citações: Nas avaliações da Anthropic, o recurso de citações tem probabilidade significativamente maior de citar os trechos mais relevantes dos documentos do que abordagens puramente baseadas em prompt.

Como as citações funcionam

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

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 dos seus documentos. Atualmente, as citações devem ser habilitadas em todos ou em nenhum dos documentos dentro de uma requisição.
- Apenas citações de texto são suportadas atualmente. Citações de imagens ainda não são possíveis.
Os documentos são processados
- O conteúdo dos documentos é dividido em "chunks" (fragmentos) para definir a granularidade mínima das citações possíveis. Por exemplo, a divisão por sentenças permite que o Claude cite uma única sentença ou encadeie várias sentenças consecutivas para citar um parágrafo ou uma passagem mais longa.
  - Para PDFs: O texto é extraído conforme descrito em Suporte a PDF e o conteúdo é dividido em sentenças. Citar imagens de PDFs não é suportado atualmente.
  - Para documentos de texto simples: O conteúdo é dividido em sentenças que podem ser citadas.
  - Para documentos de conteúdo personalizado: Os blocos de conteúdo que você fornece são usados como estão e nenhuma divisão adicional é feita.
O Claude fornece uma resposta com citações
- As respostas agora podem incluir vários blocos de texto, onde cada bloco de texto pode conter uma afirmação que o Claude está fazendo e uma lista de citações que sustentam essa afirmação.
- As citações referenciam localizações específicas nos documentos de origem. O formato dessas citações depende do tipo de documento que está sendo citado.
  - Para PDFs: As citações incluem o intervalo de números de página (indexado a partir de 1).
  - Para documentos de texto simples: As citações incluem o intervalo de índices de caracteres (indexado a partir de 0).
  - Para documentos de conteúdo personalizado: As citações incluem o intervalo de índices de blocos de conteúdo (indexado a partir de 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 a partir de 0 de acordo com a lista de todos os documentos na sua requisição original.

Divisão automática vs conteúdo personalizado

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

Os í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).
Os índices de caracteres são indexados a partir de 0 com índices finais exclusivos.
Os números de página são indexados a partir de 1 com números de página finais exclusivos.
Os í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 do documento. O campo cited_text é fornecido por conveniência e não conta para os tokens de saída.
Quando passado de volta em turnos de conversa subsequentes, 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.

Citações e saídas estruturadas são incompatíveis

Isso ocorre porque as citações exigem a intercalação de blocos de citação com a saída de texto, o que é incompatível com as restrições estritas de esquema JSON das saídas estruturadas.

Usando cache de prompt com citações

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

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-4-8",
    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 do documento.
As citações sã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

Tipo	Melhor para	Divisão em chunks	Formato de citação
Texto simples	Documentos de texto simples, prosa	Sentença	Índices de caracteres (indexados a partir de 0)
PDF	Arquivos PDF com conteúdo de texto	Sentença	Números de página (indexados a partir de 1)
Conteúdo personalizado	Listas, transcrições, formatação especial, citações mais granulares	Sem divisão adicional	Índices de blocos (indexados a partir de 0)

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

client = anthropic.Anthropic()

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

Próximos passos

Mensagens em streaming

Trate o tipo de delta citations_delta junto com os deltas de texto para renderizar respostas citadas à medida que são transmitidas.

Resultados de busca

Passe resultados de busca do seu pipeline de RAG como blocos de conteúdo de primeira classe com suporte integrado a citações.

Suporte a PDF

Saiba como o Claude extrai texto de PDFs e como as citações baseadas em páginas são mapeadas de volta para seus arquivos de origem.

Files API

Faça upload de documentos uma vez e referencie-os por file_id em várias requisições de citação.

Was this page helpful?

Como as citações funcionam

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

Índices de citação

Custos de tokens

Compatibilidade de recursos

Usando cache de prompt com citações

Tipos de documentos

Escolhendo um tipo de documento

Documentos de texto simples

Exemplo de citação de texto simples

Documentos PDF

Exemplo de citação de PDF

Documentos de conteúdo personalizado

Exemplo de citação

Estrutura da resposta

Suporte a streaming

Exemplo de eventos de streaming

Próximos passos

Como as citações funcionam

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

Índices de citação

Custos de tokens

Compatibilidade de recursos

Usando cache de prompt com citações

Tipos de documentos

Escolhendo um tipo de documento

Documentos de texto simples

Exemplo de citação de texto simples

Documentos PDF

Exemplo de citação de PDF

Documentos de conteúdo personalizado

Exemplo de citação

Estrutura da resposta

Suporte a streaming

Exemplo de eventos de streaming

Próximos passos

Como as citações funcionam

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

Índices de citação

Custos de tokens

Compatibilidade de recursos

Usando cache de prompt com citações

Tipos de documentos

Escolhendo um tipo de documento

Documentos de texto simples

Documentos PDF

Documentos de conteúdo personalizado

Estrutura da resposta

Suporte a streaming

Próximos passos

Como as citações funcionam

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

Índices de citação

Custos de tokens

Compatibilidade de recursos

Usando cache de prompt com citações

Tipos de documentos

Escolhendo um tipo de documento

Documentos de texto simples

Documentos PDF

Documentos de conteúdo personalizado

Estrutura da resposta

Suporte a streaming

Próximos passos