訊息模型功能

引用

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

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

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

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

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

以下範例展示如何透過 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)

與基於提示的方法比較

與透過提示要求 Claude 引用來源相比，引用功能具有以下優勢：

節省成本： 如果您基於提示的方法要求 Claude 輸出直接引文，您可能會看到成本節省，因為 cited_text 不計入您的輸出 token。
更好的引用可靠性： 由於 API 會將引用解析為以下章節所述的回應格式，並直接擷取 cited_text，因此保證引用包含指向所提供文件的有效指標。
更高的引用品質： 在 Anthropic 的評估中，引用功能比純粹基於提示的方法更有可能引用文件中最相關的引文。

引用功能的運作方式

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

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

自動分塊與自訂內容

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

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

可引用與不可引用的內容

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

引用索引

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

Token 成本

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

功能相容性

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

引用與結構化輸出不相容

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

這是因為引用功能需要將引用區塊與文字輸出交錯排列，這與結構化輸出的嚴格 JSON 結構描述限制不相容。

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

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

回應中產生的引用區塊無法直接快取，但它們所參照的來源文件可以被快取。為了最佳化效能，請將 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-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)

在此範例中：

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

文件類型

選擇文件類型

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

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

對於 document 區塊不支援的檔案類型（例如 .docx 和 .xlsx），請將檔案轉換為純文字並將內容直接包含在訊息內容中。已經是純文字的檔案（例如 .csv 和 .md 檔案）也可以使用明確的 text/plain 內容類型上傳。請參閱處理其他檔案格式。

純文字文件

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

PDF 文件

PDF 文件可以以 base64 編碼資料、URL 或 file_id 的形式提供。PDF 文字會被擷取並分塊為句子。由於尚不支援圖片引用，因此屬於文件掃描檔且不包含可擷取文字的 PDF 將無法被引用。

自訂內容文件

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

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)

回應結構

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

{
    "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 差異類型的形式出現在 content_block_delta 事件中。每個差異包含一個要新增到目前 text 內容區塊的 citations 列表中的單一引用。

後續步驟

串流訊息

在處理文字差異的同時處理 citations_delta 差異類型，以便在串流時呈現帶有引用的回應。

搜尋結果

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

PDF 支援

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

Files API

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

Was this page helpful?

訊息模型功能

引用

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

此功能符合「Zero Data Retention」（零資料保留），即 ZDR 的資格。當您的組織具有 ZDR 安排時，透過此功能傳送的資料在 API 回應返回後不會被儲存。

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

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

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

以下範例展示如何透過 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)

與基於提示的方法比較

與透過提示要求 Claude 引用來源相比，引用功能具有以下優勢：

節省成本： 如果您基於提示的方法要求 Claude 輸出直接引文，您可能會看到成本節省，因為 cited_text 不計入您的輸出 token。
更好的引用可靠性： 由於 API 會將引用解析為以下章節所述的回應格式，並直接擷取 cited_text，因此保證引用包含指向所提供文件的有效指標。
更高的引用品質： 在 Anthropic 的評估中，引用功能比純粹基於提示的方法更有可能引用文件中最相關的引文。

引用功能的運作方式

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

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

自動分塊與自訂內容

可引用與不可引用的內容

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

引用索引

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

Token 成本

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

功能相容性

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

引用與結構化輸出不相容

這是因為引用功能需要將引用區塊與文字輸出交錯排列，這與結構化輸出的嚴格 JSON 結構描述限制不相容。

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

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

回應中產生的引用區塊無法直接快取，但它們所參照的來源文件可以被快取。為了最佳化效能，請將 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-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)

在此範例中：

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

文件類型

選擇文件類型

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

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

純文字文件

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

PDF 文件

自訂內容文件

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

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)

回應結構

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

{
    "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 差異類型，以便在串流時呈現帶有引用的回應。

搜尋結果

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

PDF 支援

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

Files API

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

Was this page helpful?

引用功能的運作方式

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

引用索引

Token 成本

功能相容性

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

文件類型

選擇文件類型

純文字文件

純文字引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例

後續步驟

引用功能的運作方式

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

引用索引

Token 成本

功能相容性

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

文件類型

選擇文件類型

純文字文件

純文字引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例

後續步驟

引用功能的運作方式

可引用與不可引用的內容

引用索引

Token 成本

功能相容性

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

文件類型

選擇文件類型

純文字文件

PDF 文件

自訂內容文件

回應結構

串流支援

後續步驟

引用功能的運作方式

可引用與不可引用的內容

引用索引

Token 成本

功能相容性

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

文件類型

選擇文件類型

純文字文件

PDF 文件

自訂內容文件

回應結構

串流支援

後續步驟