機能

引用

Claudeは、ドキュメントに関する質問に回答する際に詳細な引用を提供する機能を備えており、レスポンス内の情報ソースの追跡と検証を支援します。

Haiku 3を除くすべてのアクティブモデルが引用をサポートしています。

Claude Sonnet 3.7での引用

Claude Sonnet 3.7は、ユーザーからのより明示的な指示がない場合、他のClaudeモデルと比較して引用を行う可能性が低い場合があります。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が出力トークンにカウントされないため、コスト削減が見込めます。
引用の信頼性向上： 引用を上記のレスポンスフォーマットに解析し、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を適用してください。

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

ドキュメントタイプ

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

引用用に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", # オプション
    "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
            }]
        }
    ]
}

ストリーミングサポート

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

Was this page helpful?

機能

引用

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が出力トークンにカウントされないため、コスト削減が見込めます。
引用の信頼性向上： 引用を上記のレスポンスフォーマットに解析し、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スキーマ制約と互換性がないためです。

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

引用とプロンプトキャッシングは効果的に組み合わせて使用できます。

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

ドキュメントタイプ

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

タイプ	最適な用途	チャンキング	引用フォーマット
プレーンテキスト	シンプルなテキストドキュメント、散文	文単位	文字インデックス（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", # オプション
    "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
            }]
        }
    ]
}

ストリーミングサポート

Was this page helpful?

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

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

PDFドキュメント

PDF引用の例

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

引用の例

レスポンス構造

ストリーミングサポート

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

引用の仕組み

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

引用インデックス

トークンコスト

機能の互換性

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

ドキュメントタイプ

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

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

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

PDFドキュメント

PDF引用の例

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

引用の例

レスポンス構造

ストリーミングサポート

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