引用 - Claude API Docs

引用

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 ドキュメントは自動的に文にチャンク化されます。引用の粒度をより細かく制御する必要がある場合（例えば、箇条書きやトランスクリプト）、代わりにカスタムコンテンツドキュメントを使用してください。詳細はドキュメントタイプを参照してください。

たとえば、Claude が RAG チャンクから特定の文を引用できるようにしたい場合は、各 RAG チャンクをプレーンテキストドキュメントに入れる必要があります。それ以外の場合、さらなるチャンク化を行いたくない場合、またはカスタムチャンク化を行いたい場合は、RAG チャンクをカスタムコンテンツドキュメントに入れることができます。

引用可能なコンテンツと引用不可能なコンテンツ

ドキュメントのsourceコンテンツ内にあるテキストは引用できます。
titleとcontextはオプションのフィールドで、モデルに渡されますが、引用されたコンテンツには使用されません。
titleは長さが制限されているため、contextフィールドがドキュメントメタデータをテキストまたは文字列化された JSON として保存するのに役立つ場合があります。

引用インデックス

ドキュメントインデックスは、リクエスト内のすべてのドキュメントコンテンツブロックのリストから 0 インデックスです（すべてのメッセージにまたがります）。
文字インデックスは 0 インデックスで、終了インデックスは排他的です。
ページ番号は 1 インデックスで、終了ページ番号は排他的です。
コンテンツブロックインデックスは、カスタムコンテンツドキュメントで提供されるcontentリストから 0 インデックスで、終了インデックスは排他的です。

トークンコスト

引用を有効にすると、システムプロンプトの追加とドキュメントチャンク化により、入力トークンがわずかに増加します。
ただし、引用機能は出力トークンで非常に効率的です。内部的には、モデルは標準化された形式で引用を出力しており、その後、引用されたテキストとドキュメント位置インデックスに解析されます。cited_textフィールドは便宜上提供されており、出力トークンにはカウントされません。
後続の会話ターンで渡される場合、cited_textも入力トークンにはカウントされません。

機能の互換性

引用は、プロンプトキャッシング、トークンカウント、バッチ処理を含む他の API 機能と組み合わせて機能します。

引用と構造化出力は互換性がありません

引用は構造化出力と一緒に使用することはできません。ユーザーが提供したドキュメント（ドキュメントブロックまたは RequestSearchResultBlock）で引用を有効にし、output_config.formatパラメータ（または非推奨のoutput_formatパラメータ）も含める場合、API は 400 エラーを返します。

これは、引用がテキスト出力と引用ブロックのインターリーブを必要とするため、構造化出力の厳密な JSON スキーマ制約と互換性がないためです。

プロンプトキャッシングと引用の使用

引用とプロンプトキャッシングは効果的に一緒に使用できます。

レスポンスで生成された引用ブロックは直接キャッシュできませんが、それらが参照するソースドキュメントはキャッシュできます。パフォーマンスを最適化するには、トップレベルのドキュメントコンテンツブロックにcache_controlを適用します。

この例では：

ドキュメントコンテンツはドキュメントブロックのcache_controlを使用してキャッシュされます
引用はドキュメントで有効になります
Claudeはキャッシュされたドキュメントコンテンツの利点を得ながら、引用付きレスポンスを生成できます
同じドキュメントを使用する後続のリクエストはキャッシュされたコンテンツの利点を得ます

ドキュメントタイプ

ドキュメントタイプの選択

引用では 3 つのドキュメントタイプがサポートされています。ドキュメントはメッセージで直接提供（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",  # 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リストに追加される単一の引用を含みます。

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)

引用の仕組み

引用可能なコンテンツと引用不可能なコンテンツ

引用インデックス

トークンコスト

機能の互換性

プロンプトキャッシングと引用の使用

ドキュメントタイプ

ドキュメントタイプの選択

プレーンテキストドキュメント

プレーンテキスト引用の例

PDF ドキュメント

PDF 引用の例

カスタムコンテンツドキュメント

引用の例

レスポンス構造

ストリーミングサポート

ストリーミングイベントの例