メッセージモデルの機能

引用

この機能はZero Data Retention（ZDR）の対象です。組織がZDR契約を締結している場合、この機能を通じて送信されたデータは、APIレスポンスが返された後に保存されることはありません。

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に直接引用を出力させている場合、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は長さに制限があるため、ドキュメントのメタデータをテキストまたは文字列化されたJSONとして保存するにはcontextフィールドが便利な場合があります。

引用インデックス

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

トークンコスト

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

機能の互換性

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

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

引用は構造化出力と併用できません。ユーザー提供のドキュメント（DocumentブロックまたはRequestSearchResultBlock）で引用を有効にし、同時に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はキャッシュされたドキュメントコンテンツの恩恵を受けながら、引用付きのレスポンスを生成できます
同じドキュメントを使用する後続のリクエストは、キャッシュされたコンテンツの恩恵を受けます

ドキュメントタイプ

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

引用では3つのドキュメントタイプがサポートされています。ドキュメントはメッセージ内で直接提供する（base64、テキスト、またはURL）か、Files API経由でアップロードしてfile_idで参照することができます。

タイプ	最適な用途	チャンク化	引用形式
プレーンテキスト	シンプルなテキストドキュメント、散文	文単位	文字インデックス（0始まり）
PDF	テキストコンテンツを含むPDFファイル	文単位	ページ番号（1始まり）
カスタムコンテンツ	リスト、トランスクリプト、特殊な書式、より細かい粒度の引用	追加のチャンク化なし	ブロックインデックス（0始まり）

.csv、.xlsx、.docx、.md、.txtファイルはドキュメントブロックとしてサポートされていません。これらはプレーンテキストに変換し、メッセージコンテンツに直接含めてください。他のファイル形式の扱い方を参照してください。

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

プレーンテキストドキュメントは自動的に文単位にチャンク化されます。インラインで提供するか、file_idで参照して提供できます。

PDFドキュメント

PDFドキュメントは、base64エンコードされたデータ、URL、または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,
                }
            ],
        },
    ]
}

ストリーミングのサポート

ストリーミングレスポンスの場合、現在のtextコンテンツブロックのcitationsリストに追加される単一の引用を含むcitations_deltaタイプが含まれます。

Was this page helpful?

メッセージモデルの機能

引用

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に直接引用を出力させている場合、cited_textは出力トークンにカウントされないため、コスト削減が見込める可能性があります。
引用の信頼性向上： 引用は上記の各レスポンス形式に解析され、cited_textが抽出されるため、引用には提供されたドキュメントへの有効なポインタが含まれることが保証されます。
引用品質の向上： 評価において、引用機能は純粋なプロンプトベースのアプローチと比較して、ドキュメントから最も関連性の高い引用を行う可能性が大幅に高いことが確認されました。

引用の仕組み

以下の手順でClaudeに引用を統合します。

ドキュメントを提供し、引用を有効にする
- サポートされている形式のいずれかでドキュメントを含めます：PDF、プレーンテキスト、またはカスタムコンテンツドキュメント
- 各ドキュメントでcitations.enabled=trueを設定します。現在、引用はリクエスト内のすべてのドキュメントで有効にするか、いずれのドキュメントでも有効にしないかのどちらかである必要があります。
- 現在サポートされているのはテキスト引用のみであり、画像引用はまだ利用できないことに注意してください。
ドキュメントが処理される
- ドキュメントの内容は、可能な引用の最小粒度を定義するために「チャンク化」されます。たとえば、文単位のチャンク化により、Claudeは単一の文を引用したり、複数の連続した文を連結して段落（またはそれ以上）を引用したりできます。
  - PDFの場合： PDFサポートで説明されているようにテキストが抽出され、コンテンツは文単位にチャンク化されます。PDFからの画像の引用は現在サポートされていません。
  - プレーンテキストドキュメントの場合： コンテンツは引用可能な文単位にチャンク化されます。
  - カスタムコンテンツドキュメントの場合： 提供されたコンテンツブロックがそのまま使用され、追加のチャンク化は行われません。
Claudeが引用付きのレスポンスを提供する
- レスポンスには複数のテキストブロックが含まれる場合があり、各テキストブロックにはClaudeが行っている主張と、その主張を裏付ける引用のリストが含まれることがあります。
- 引用はソースドキュメント内の特定の位置を参照します。これらの引用の形式は、引用元のドキュメントの種類によって異なります。
  - PDFの場合： 引用にはページ番号の範囲（1始まり）が含まれます。
  - プレーンテキストドキュメントの場合： 引用には文字インデックスの範囲（0始まり）が含まれます。
  - カスタムコンテンツドキュメントの場合： 引用には、提供された元のコンテンツリストに対応するコンテンツブロックインデックスの範囲（0始まり）が含まれます。
- ドキュメントインデックスは参照元を示すために提供され、元のリクエスト内のすべてのドキュメントのリストに従って0始まりでインデックス付けされます。

自動チャンク化とカスタムコンテンツの比較

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

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

引用インデックス

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

トークンコスト

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

機能の互換性

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

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

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

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

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

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はキャッシュされたドキュメントコンテンツの恩恵を受けながら、引用付きのレスポンスを生成できます
同じドキュメントを使用する後続のリクエストは、キャッシュされたコンテンツの恩恵を受けます

ドキュメントタイプ

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

タイプ	最適な用途	チャンク化	引用形式
プレーンテキスト	シンプルなテキストドキュメント、散文	文単位	文字インデックス（0始まり）
PDF	テキストコンテンツを含むPDFファイル	文単位	ページ番号（1始まり）
カスタムコンテンツ	リスト、トランスクリプト、特殊な書式、より細かい粒度の引用	追加のチャンク化なし	ブロックインデックス（0始まり）

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

プレーンテキストドキュメントは自動的に文単位にチャンク化されます。インラインで提供するか、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,
                }
            ],
        },
    ]
}

ストリーミングのサポート

Was this page helpful?

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

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

PDFドキュメント

PDF引用の例

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

引用の例

レスポンス構造

ストリーミングのサポート

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

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

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

PDFドキュメント

PDF引用の例

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

引用の例

レスポンス構造

ストリーミングのサポート

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

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

PDFドキュメント

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

レスポンス構造

ストリーミングのサポート

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

PDFドキュメント

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

レスポンス構造

ストリーミングのサポート