Claude 能夠在回答關於文件的問題時提供詳細的引用，幫助您追蹤和驗證回應中的信息來源。

引用功能目前在 Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5（新版）和 Haiku 3.5 上可用。

使用 Claude Sonnet 3.7 的引用功能

與其他 Claude 模型相比，如果沒有用戶更明確的指示，Claude Sonnet 3.7 可能不太會使用引用。當使用 Claude Sonnet 3.7 的引用功能時，我們建議在 user 回合中包含額外的指示，例如 "使用引用來支持你的回答。"

我們還觀察到，當要求模型結構化其回應時，除非明確告知在該格式內使用引用，否則它不太可能使用引用。例如，如果要求模型在回應中使用 標籤，您應該添加類似 “在你的回答中始終使用引用，即使在 內也要使用。” 的內容。

請使用此表單分享您對引用功能的反饋和建議。

以下是如何使用 Messages API 進行引用的示例：

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?"
          }
        ]
      }
    ]
  }'

與基於提示的方法比較

與基於提示的引用解決方案相比，引用功能具有以下優勢：

  • 成本節省： 如果您的基於提示的方法要求 Claude 輸出直接引用，由於 cited_text 不計入您的輸出令牌，您可能會看到成本節省。
  • 更可靠的引用： 因為我們將引用解析為上述相應的響應格式並提取 cited_text，引用保證包含對所提供文檔的有效指針。
  • 改進的引用質量： 在我們的評估中，我們發現引用功能與純粹基於提示的方法相比，更有可能引用文檔中最相關的引述。

​
引用功能如何工作

通過以下步驟將引用與 Claude 整合：

1

提供文檔並啟用引用

  • 以任何支持的格式包含文檔：PDF、純文本 或 自定義內容 文檔
  • 在每個文檔上設置 citations.enabled=true。目前，必須在請求中的所有文檔上啟用引用，或者都不啟用。
  • 請注意，目前僅支持文本引用，尚不支持圖像引用。
2

文檔處理過程

  • 文檔內容被”分塊”，以定義可能引用的最小粒度。例如，句子分塊將允許 Claude 引用單個句子或將多個連續句子鏈接在一起以引用段落（或更長的內容）！
    • 對於 PDF： 文本提取如 PDF 支持 中所述，內容被分成句子。目前不支持從 PDF 引用圖像。
    • 對於純文本文檔： 內容被分成可以引用的句子。
    • 對於自定義內容文檔： 您提供的內容塊按原樣使用，不進行進一步分塊。
3

Claude 提供帶引用的回應

  • 回應現在可能包含多個文本塊，每個文本塊可以包含 Claude 做出的聲明和支持該聲明的引用列表。
  • 引用參考源文檔中的特定位置。這些引用的格式取決於被引用的文檔類型。
    • 對於 PDF： 引用將包括頁碼範圍（從 1 開始編號）。
    • 對於純文本文檔： 引用將包括字符索引範圍（從 0 開始編號）。
    • 對於自定義內容文檔： 引用將包括內容塊索引範圍（從 0 開始編號），對應於原始提供的內容列表。
  • 提供文檔索引以指示參考源，並根據原始請求中所有文檔的列表從 0 開始編號。

自動分塊與自定義內容

默認情況下，純文本和 PDF 文檔會自動分成句子。如果您需要更精細地控制引用粒度（例如，對於項目符號或轉錄），請改用自定義內容文檔。有關更多詳細信息，請參閱文檔類型。

例如，如果您希望 Claude 能夠引用 RAG 塊中的特定句子，您應該將每個 RAG 塊放入純文本文檔中。否則，如果您不希望進行任何進一步的分塊，或者如果您想自定義任何額外的分塊，您可以將 RAG 塊放入自定義內容文檔中。

​
可引用與不可引用的內容

  • 文檔 source 內容中的文本可以被引用。
  • title 和 context 是可選字段，將傳遞給模型但不用於引用內容。
  • title 的長度有限，因此您可能會發現 context 字段對於以文本或字符串化 JSON 存儲任何文檔元數據很有用。

​
引用索引

  • 文檔索引是從請求中所有文檔內容塊的列表（跨所有消息）從 0 開始編號的。
  • 字符索引是從 0 開始編號的，結束索引是排他的。
  • 頁碼是從 1 開始編號的，結束頁碼是排他的。
  • 內容塊索引是從自定義內容文檔中提供的 content 列表中從 0 開始編號的，結束索引是排他的。

​
令牌成本

  • 啟用引用會因系統提示添加和文檔分塊而導致輸入令牌略微增加。
  • 然而，引用功能在輸出令牌方面非常高效。在底層，模型以標準化格式輸出引用，然後解析為引用文本和文檔位置索引。cited_text 字段是為了方便而提供的，不計入輸出令牌。
  • 在後續對話回合中傳遞時，cited_text 也不計入輸入令牌。

​
功能兼容性

引用功能與其他 API 功能一起工作，包括提示緩存、令牌計數和批處理。

​
將提示緩存與引用一起使用

引用和提示緩存可以有效地一起使用。

回應中生成的引用塊不能直接緩存，但它們引用的源文檔可以緩存。為了優化性能，將 cache_control 應用於頂級文檔內容塊。

import anthropic

client = anthropic.Anthropic()

# 長文檔內容（例如，技術文檔）
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # 最小可緩存長度

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"}  # 緩存文檔內容
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

在此示例中：

  • 文檔內容使用文檔塊上的 cache_control 進行緩存
  • 在文檔上啟用了引用
  • Claude 可以生成帶有引用的回應，同時受益於緩存的文檔內容
  • 使用相同文檔的後續請求將受益於緩存的內容

​
文檔類型

​
選擇文檔類型

我們支持三種用於引用的文檔類型。文檔可以直接在消息中提供（base64、文本或 URL）或通過 Files API 上傳並通過 file_id 引用：

類型最適合分塊引用格式
純文本簡單文本文檔、散文句子字符索引（從 0 開始編號）
PDF包含文本內容的 PDF 文件句子頁碼（從 1 開始編號）
自定義內容列表、轉錄、特殊格式、更精細的引用無額外分塊塊索引（從 0 開始編號）

​
純文本文檔

純文本文檔會自動分成句子。您可以內聯提供它們或通過 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}
}

​
PDF 文檔

PDF 文檔可以作為 base64 編碼數據提供或通過 file_id 提供。PDF 文本被提取並分成句子。由於尚不支持圖像引用，作為文檔掃描且不包含可提取文本的 PDF 將無法被引用。

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data
    },
    "title": "Document Title", # 可選
    "context": "Context about the document that will not be cited from", # 可選
    "citations": {"enabled": True}
}

​
自定義內容文檔

自定義內容文檔讓您控制引用粒度。不進行額外分塊，根據提供的內容塊向模型提供塊。

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

​
回應結構

啟用引用時，回應包括帶有引用的多個文本塊：

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

​
流式傳輸支持

對於流式回應，我們添加了 citations_delta 類型，其中包含要添加到當前 text 內容塊的 citations 列表中的單個引用。