Claude Platform Docs
Messages模型功能

引用

讓 Claude 的回應以您的來源文件為依據。引用功能會回傳支持每項主張的確切段落，讓您能夠驗證答案並向使用者呈現來源。

Claude 在回答有關文件的問題時可以提供詳細的「citations」（引用），協助您追蹤並驗證每個回應背後的來源。

所有現行模型皆支援引用功能。

以下範例展示如何使用 Messages API 在純文字文件上啟用引用功能：

client = anthropic.Anthropic()

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

引用功能的運作方式

請依照以下步驟將引用功能與 Claude 整合：

  1. 提供文件並啟用引用功能

    • 以任何支援的格式納入文件：PDF、純文字或自訂內容文件。
    • 在每份文件上設定 citations.enabled=true。目前，在單一請求中，必須對所有文件全部啟用或全部不啟用引用功能。
    • 目前僅支援文字引用，尚無法進行圖片引用。

  2. 文件進行處理

    • 文件內容會被「chunked」（分塊），以定義可能引用的最小粒度。例如，句子分塊讓 Claude 能夠引用單一句子，或將多個連續句子串接起來以引用一個段落或更長的篇幅。
      • **對於 PDF：**文字會依照 PDF 支援中所述的方式擷取，內容會被分塊為句子。目前不支援引用 PDF 中的圖片。
      • **對於純文字文件：**內容會被分塊為可供引用的句子。
      • **對於自訂內容文件：**您提供的內容區塊會按原樣使用，不會進行進一步分塊。

  3. Claude 提供附帶引用的回應

    • 回應現在可能包含多個文字區塊，每個文字區塊可包含 Claude 提出的一項主張，以及支持該主張的引用清單。
    • 引用會參照來源文件中的特定位置。這些引用的格式取決於所引用文件的類型。
      • **對於 PDF：**引用包含頁碼範圍（從 1 開始索引）。
      • **對於純文字文件：**引用包含字元索引範圍（從 0 開始索引）。
      • **對於自訂內容文件：**引用包含內容區塊索引範圍（從 0 開始索引），對應於原始提供的內容清單。
    • 文件索引用於指示參照來源，並依據您原始請求中所有文件的清單從 0 開始索引。

可引用與不可引用的內容

  • 文件 source 內容中的文字可供引用。
  • title 和 context 是選用欄位，會傳遞給模型，但不會用於引用內容。
  • title 有長度限制，因此 context 欄位適合用來以文字或字串化 JSON 的形式儲存文件中繼資料。

引用索引

  • 文件索引依據請求中所有文件內容區塊的清單（跨越所有訊息）從 0 開始索引。
  • 字元索引從 0 開始，結束索引為不包含（exclusive）。
  • 頁碼從 1 開始，結束頁碼為不包含（exclusive）。
  • 內容區塊索引依據自訂內容文件中提供的 content 清單從 0 開始，結束索引為不包含（exclusive）。

Token 成本

  • 啟用引用功能會因系統提示的新增內容與文件分塊而使輸入 token 略微增加。
  • 然而，引用功能在輸出 token 方面非常有效率。在內部，模型會以標準化格式輸出引用，然後再解析為引用文字與文件位置索引。cited_text 欄位是為了方便而提供，不計入輸出 token。
  • 在後續對話輪次中傳回時，cited_text 同樣不計入輸入 token。

功能相容性

引用功能可與其他 API 功能搭配使用，包括「prompt caching」（提示快取）（請參閱提示快取）、token 計數以及批次處理。

搭配引用功能使用提示快取

引用功能與提示快取可以有效地搭配使用。

回應中產生的引用區塊無法直接快取，但它們所參照的來源文件可以快取。為了最佳化效能，請將 cache_control 套用至您的頂層文件內容區塊。

client = anthropic.Anthropic()

# 長篇文件內容（例如技術文件）
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

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

在此範例中：

  • 文件內容透過文件區塊上的 cache_control 進行快取。
  • 文件上已啟用引用功能。
  • Claude 可以在受益於已快取文件內容的同時，產生附帶引用的回應。
  • 後續使用相同文件的請求可受益於已快取的內容。

文件類型

選擇文件類型

引用功能支援三種文件類型。文件可以直接在訊息中提供（base64、文字或 URL），或透過 Files API 上傳並以 file_id 參照：

類型最適用於分塊方式引用格式
純文字簡單的文字文件、散文句子字元索引（從 0 開始）
PDF含文字內容的 PDF 檔案句子頁碼（從 1 開始）
自訂內容清單、逐字稿、特殊格式、更細粒度的引用無額外分塊區塊索引（從 0 開始）

純文字文件

純文字文件會自動分塊為句子。您可以以內嵌方式提供，或透過其 file_id 以參照方式提供：

本頁頂部的入門範例展示了各 SDK 中完整的純文字請求。文件區塊使用 text 來源：

{
  "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 編碼資料、URL 或 file_id 的形式提供。PDF 文字會被擷取並分塊為句子。由於尚不支援圖片引用，屬於文件掃描檔且不含可擷取文字的 PDF 無法被引用。

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "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)

自訂內容文件

自訂內容文件讓您能夠控制引用粒度。不會進行額外分塊，區塊會依據所提供的內容區塊提供給模型。

client = anthropic.Anthropic()

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

回應結構

啟用引用功能後，回應會包含多個附帶引用的文字區塊：

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

串流支援

對於「streaming」（串流）回應，引用會以 content_block_delta 事件中的 citations_delta delta 類型送達。每個 delta 包含單一引用，用於新增至目前 text 內容區塊的 citations 清單中。

後續步驟

串流訊息

在處理文字 delta 的同時處理 citations_delta delta 類型，以便在串流過程中呈現附帶引用的回應。

搜尋結果

將 RAG 管線中的搜尋結果作為具備內建引用支援的一級內容區塊傳遞。

PDF 支援

了解 Claude 如何從 PDF 擷取文字，以及基於頁碼的引用如何對應回您的來源檔案。

Files API

上傳文件一次，即可在多個引用請求中透過 file_id 參照它們。

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?