功能

引用

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

所有現行模型都支援引用，但 Haiku 3 除外。

使用 Claude Sonnet 3.7 的引用

與其他 Claude 模型相比，Claude Sonnet 3.7 在沒有使用者更明確指示的情況下，可能較不傾向於進行引用。當使用 Claude Sonnet 3.7 的引用功能時，我們建議在 user 輪次中加入額外的指示，例如 "Use citations to back up your answer."。

我們也觀察到，當要求模型結構化其回應時，除非明確告知在該格式中使用引用，否則模型不太可能使用引用。例如，如果要求模型在回應中使用 <result> 標籤，您應該加入類似 "Always use citations in your answer, even within <result> tags." 的指示。

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

以下是如何在 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-6",
    "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 不計入您的輸出 token。
更好的引用可靠性： 因為我們將引用解析為上述相應的回應格式並提取 cited_text，引用保證包含指向所提供文件的有效指標。
改善的引用品質： 在我們的評估中，我們發現引用功能比純粹基於提示詞的方法更有可能從文件中引用最相關的引文。

引用的運作方式

按照以下步驟將引用與 Claude 整合：

提供文件並啟用引用
- 以任何支援的格式包含文件：PDF、純文字或自訂內容文件
- 在每個文件上設定 citations.enabled=true。目前，引用必須在請求中的所有文件上全部啟用或全部不啟用。
- 請注意，目前僅支援文字引用，尚不支援圖片引用。
文件被處理
- 文件內容會被「分塊」以定義可能引用的最小粒度。例如，句子分塊將允許 Claude 引用單一句子或將多個連續句子串聯起來以引用一個段落（或更長的內容）！
  - 對於 PDF： 文字按照 PDF 支援中描述的方式提取，內容被分塊為句子。目前不支援從 PDF 引用圖片。
  - 對於純文字文件： 內容被分塊為可引用的句子。
  - 對於自訂內容文件： 您提供的內容區塊按原樣使用，不進行進一步分塊。
Claude 提供帶引用的回應
- 回應現在可能包含多個文字區塊，其中每個文字區塊可以包含 Claude 提出的主張以及支持該主張的引用列表。
- 引用參考來源文件中的特定位置。這些引用的格式取決於被引用的文件類型。
  - 對於 PDF： 引用將包含頁碼範圍（從 1 開始索引）。
  - 對於純文字文件： 引用將包含字元索引範圍（從 0 開始索引）。
  - 對於自訂內容文件： 引用將包含內容區塊索引範圍（從 0 開始索引），對應於所提供的原始內容列表。
- 提供文件索引以指示參考來源，根據您原始請求中所有文件的列表從 0 開始索引。

自動分塊 vs 自訂內容

預設情況下，純文字和 PDF 文件會自動分塊為句子。如果您需要更多控制引用粒度（例如，用於項目符號列表或逐字稿），請改用自訂內容文件。詳情請參閱文件類型。

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

可引用 vs 不可引用的內容

在文件的 source 內容中找到的文字可以被引用。
title 和 context 是可選欄位，將傳遞給模型但不用於被引用的內容。
title 的長度有限，因此您可能會發現 context 欄位對於以文字或字串化 JSON 儲存任何文件中繼資料很有用。

引用索引

文件索引從請求中所有文件內容區塊的列表（跨所有訊息）從 0 開始索引。
字元索引從 0 開始索引，結束索引為排他性的。
頁碼從 1 開始索引，結束頁碼為排他性的。
內容區塊索引從自訂內容文件中提供的 content 列表從 0 開始索引，結束索引為排他性的。

Token 成本

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

功能相容性

引用可與其他 API 功能配合使用，包括提示詞快取、token 計數和批次處理。

引用與結構化輸出不相容

引用不能與結構化輸出一起使用。如果您在任何使用者提供的文件（Document 區塊或 RequestSearchResultBlock）上啟用引用，同時也包含 output_config.format 參數（或已棄用的 output_format 參數），API 將返回 400 錯誤。

這是因為引用需要在文字輸出中交錯插入引用區塊，這與結構化輸出的嚴格 JSON schema 約束不相容。

搭配引用使用提示詞快取

引用和提示詞快取可以有效地一起使用。

回應中生成的引用區塊不能直接快取，但它們參考的來源文件可以被快取。為了優化效能，請將 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-6",
    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 開始）

不支援 .csv、.xlsx、.docx、.md 和 .txt 檔案作為文件區塊。請將這些轉換為純文字並直接包含在訊息內容中。請參閱處理其他檔案格式。

純文字文件

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

PDF 文件

PDF 文件可以作為 base64 編碼資料或透過 file_id 提供。PDF 文字會被提取並分塊為句子。由於尚不支援圖片引用，掃描的文件且不包含可提取文字的 PDF 將無法被引用。

自訂內容文件

自訂內容文件讓您控制引用粒度。不進行額外分塊，區塊根據提供的內容區塊傳遞給模型。

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

串流支援

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

Was this page helpful?

功能

引用

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

所有現行模型都支援引用，但 Haiku 3 除外。

使用 Claude Sonnet 3.7 的引用

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

以下是如何在 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-6",
    "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 不計入您的輸出 token。
更好的引用可靠性： 因為我們將引用解析為上述相應的回應格式並提取 cited_text，引用保證包含指向所提供文件的有效指標。
改善的引用品質： 在我們的評估中，我們發現引用功能比純粹基於提示詞的方法更有可能從文件中引用最相關的引文。

引用的運作方式

按照以下步驟將引用與 Claude 整合：

提供文件並啟用引用
- 以任何支援的格式包含文件：PDF、純文字或自訂內容文件
- 在每個文件上設定 citations.enabled=true。目前，引用必須在請求中的所有文件上全部啟用或全部不啟用。
- 請注意，目前僅支援文字引用，尚不支援圖片引用。
文件被處理
- 文件內容會被「分塊」以定義可能引用的最小粒度。例如，句子分塊將允許 Claude 引用單一句子或將多個連續句子串聯起來以引用一個段落（或更長的內容）！
  - 對於 PDF： 文字按照 PDF 支援中描述的方式提取，內容被分塊為句子。目前不支援從 PDF 引用圖片。
  - 對於純文字文件： 內容被分塊為可引用的句子。
  - 對於自訂內容文件： 您提供的內容區塊按原樣使用，不進行進一步分塊。
Claude 提供帶引用的回應
- 回應現在可能包含多個文字區塊，其中每個文字區塊可以包含 Claude 提出的主張以及支持該主張的引用列表。
- 引用參考來源文件中的特定位置。這些引用的格式取決於被引用的文件類型。
  - 對於 PDF： 引用將包含頁碼範圍（從 1 開始索引）。
  - 對於純文字文件： 引用將包含字元索引範圍（從 0 開始索引）。
  - 對於自訂內容文件： 引用將包含內容區塊索引範圍（從 0 開始索引），對應於所提供的原始內容列表。
- 提供文件索引以指示參考來源，根據您原始請求中所有文件的列表從 0 開始索引。

自動分塊 vs 自訂內容

可引用 vs 不可引用的內容

在文件的 source 內容中找到的文字可以被引用。
title 和 context 是可選欄位，將傳遞給模型但不用於被引用的內容。
title 的長度有限，因此您可能會發現 context 欄位對於以文字或字串化 JSON 儲存任何文件中繼資料很有用。

引用索引

文件索引從請求中所有文件內容區塊的列表（跨所有訊息）從 0 開始索引。
字元索引從 0 開始索引，結束索引為排他性的。
頁碼從 1 開始索引，結束頁碼為排他性的。
內容區塊索引從自訂內容文件中提供的 content 列表從 0 開始索引，結束索引為排他性的。

Token 成本

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

功能相容性

引用可與其他 API 功能配合使用，包括提示詞快取、token 計數和批次處理。

引用與結構化輸出不相容

這是因為引用需要在文字輸出中交錯插入引用區塊，這與結構化輸出的嚴格 JSON schema 約束不相容。

搭配引用使用提示詞快取

引用和提示詞快取可以有效地一起使用。

回應中生成的引用區塊不能直接快取，但它們參考的來源文件可以被快取。為了優化效能，請將 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-6",
    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 開始）

不支援 .csv、.xlsx、.docx、.md 和 .txt 檔案作為文件區塊。請將這些轉換為純文字並直接包含在訊息內容中。請參閱處理其他檔案格式。

純文字文件

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

PDF 文件

自訂內容文件

自訂內容文件讓您控制引用粒度。不進行額外分塊，區塊根據提供的內容區塊傳遞給模型。

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

串流支援

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

Was this page helpful?

引用的運作方式

可引用 vs 不可引用的內容

引用索引

Token 成本

功能相容性

搭配引用使用提示詞快取

文件類型

選擇文件類型

純文字文件

純文字引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例

引用的運作方式

可引用 vs 不可引用的內容

引用索引

Token 成本

功能相容性

搭配引用使用提示詞快取

文件類型

選擇文件類型

純文字文件

純文字引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例