引用

建構模型功能

引用

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

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

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

所有活躍模型都支援引用，除了 Haiku 3。

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

以下是如何在 Messages API 中使用引用的範例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 輸出直接引用，您可能會看到成本節省，因為 cited_text 不計入您的輸出令牌。
更好的引用可靠性： 因為引用被解析為上述各自的回應格式，並且 cited_text 被提取，引用保證包含指向提供的文件的有效指標。
改進的引用品質： 在評估中，引用功能被發現比純基於提示的方法更可能引用文件中最相關的引用。

引用如何運作

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

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

自動分塊與自訂內容

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

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

可引用與不可引用的內容

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

引用索引

文件索引從請求中所有文件內容塊的列表進行 0 索引（跨越所有消息）。
字符索引為 0 索引，具有排他性結束索引。
頁碼為 1 索引，具有排他性結束頁碼。
內容塊索引為 0 索引，具有排他性結束索引，來自自訂內容文件中提供的 content 列表。

令牌成本

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

功能相容性

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

引用和結構化輸出不相容

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

這是因為引用需要將引用塊與文本輸出交錯，這與結構化輸出的嚴格 JSON 架構約束不相容。

將提示快取與引用一起使用

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

回應中生成的引用塊不能直接快取，但它們參考的源文件可以快取。為了優化效能，將 cache_control 應用於您的頂級文件內容塊。

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    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），也可以通過檔案 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",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "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 可以在回答有關文件的問題時提供詳細的引用，幫助您追蹤和驗證回應中的資訊來源。

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

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

所有活躍模型都支援引用，除了 Haiku 3。

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

以下是如何在 Messages API 中使用引用的範例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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 輸出直接引用，您可能會看到成本節省，因為 cited_text 不計入您的輸出令牌。
更好的引用可靠性： 因為引用被解析為上述各自的回應格式，並且 cited_text 被提取，引用保證包含指向提供的文件的有效指標。
改進的引用品質： 在評估中，引用功能被發現比純基於提示的方法更可能引用文件中最相關的引用。

引用如何運作

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

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

自動分塊與自訂內容

可引用與不可引用的內容

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

引用索引

文件索引從請求中所有文件內容塊的列表進行 0 索引（跨越所有消息）。
字符索引為 0 索引，具有排他性結束索引。
頁碼為 1 索引，具有排他性結束頁碼。
內容塊索引為 0 索引，具有排他性結束索引，來自自訂內容文件中提供的 content 列表。

令牌成本

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

功能相容性

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

引用和結構化輸出不相容

這是因為引用需要將引用塊與文本輸出交錯，這與結構化輸出的嚴格 JSON 架構約束不相容。

將提示快取與引用一起使用

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

回應中生成的引用塊不能直接快取，但它們參考的源文件可以快取。為了優化效能，將 cache_control 應用於您的頂級文件內容塊。

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    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），也可以通過檔案 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",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "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?

引用如何運作

可引用與不可引用的內容

引用索引

令牌成本

功能相容性

將提示快取與引用一起使用

文件類型

選擇文件類型

純文本文件

純文本引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例

引用如何運作

可引用與不可引用的內容

引用索引

令牌成本

功能相容性

將提示快取與引用一起使用

文件類型

選擇文件類型

純文本文件

純文本引用範例

PDF 文件

PDF 引用範例

自訂內容文件

引用範例

回應結構

串流支援

串流事件範例