引用

Claudeはドキュメントに関する質問に答える際に詳細な「citations」（引用）を提供でき、各応答の背後にあるソースを追跡および検証するのに役立ちます。

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

次の例は、Messages APIでプレーンテキストドキュメントに対して引用を有効にする方法を示しています。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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に引用を統合します。

1. 1

   ドキュメントを提供し、引用を有効にする

   • サポートされているいずれかの形式でドキュメントを含めます：PDF、プレーンテキスト、またはカスタムコンテンツドキュメント。
   • 各ドキュメントにcitations.enabled=trueを設定します。現在、引用はリクエスト内のすべてのドキュメントで有効にするか、すべてで無効にする必要があります。
   • 現在サポートされているのはテキストの引用のみです。画像の引用はまだできません。
2. 2

   ドキュメントが処理される

   • ドキュメントの内容は、可能な引用の最小粒度を定義するために「チャンク化」されます。たとえば、文単位のチャンク化により、Claudeは単一の文を引用したり、連続する複数の文をつなげて段落やより長い一節を引用したりできます。
     • PDFの場合： PDFサポートで説明されているようにテキストが抽出され、内容が文単位にチャンク化されます。PDFからの画像の引用は現在サポートされていません。
     • プレーンテキストドキュメントの場合： 内容は引用可能な文単位にチャンク化されます。
     • カスタムコンテンツドキュメントの場合： 提供されたコンテンツブロックがそのまま使用され、それ以上のチャンク化は行われません。
3. 3

   Claudeが引用付きの応答を提供する

   • 応答には複数のテキストブロックが含まれる場合があり、各テキストブロックにはClaudeが行う主張と、その主張を裏付ける引用のリストを含めることができます。
   • 引用はソースドキュメント内の特定の位置を参照します。これらの引用の形式は、引用元のドキュメントの種類によって異なります。
     • PDFの場合： 引用にはページ番号の範囲（1始まり）が含まれます。
     • プレーンテキストドキュメントの場合： 引用には文字インデックスの範囲（0始まり）が含まれます。
     • カスタムコンテンツドキュメントの場合： 引用には、提供された元のコンテンツリストに対応するコンテンツブロックインデックスの範囲（0始まり）が含まれます。
   • 参照元を示すためにドキュメントインデックスが提供され、元のリクエスト内のすべてのドキュメントのリストに従って0始まりで番号付けされます。

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

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

引用インデックス

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

トークンコスト

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

機能の互換性

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

引用でプロンプトキャッシングを使用する

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

応答で生成された引用ブロックを直接キャッシュすることはできませんが、それらが参照するソースドキュメントはキャッシュできます。パフォーマンスを最適化するには、トップレベルのドキュメントコンテンツブロックに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-5-5",
    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で参照できます。

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

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

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

{
  "type": "char_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_char_index": 0, // 0-indexed
  "end_char_index": 50 // exclusive
}

PDFドキュメント

PDFドキュメントは、base64エンコードされたデータ、URL、またはfile_idで提供できます。PDFのテキストは抽出され、文単位にチャンク化されます。画像の引用はまだサポートされていないため、ドキュメントをスキャンしたもので抽出可能なテキストを含まないPDFは引用できません。

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "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)

{
  "type": "page_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_page_number": 1, // 1-indexed
  "end_page_number": 2 // exclusive
}

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

カスタムコンテンツドキュメントでは、引用の粒度を制御できます。追加のチャンク化は行われず、提供されたコンテンツブロックに従ってチャンクがモデルに提供されます。

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    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)

{
  "type": "content_block_location",
  "cited_text": "The exact text being cited", // not counted toward output tokens
  "document_index": 0,
  "document_title": "Document Title",
  "start_block_index": 0, // 0-indexed
  "end_block_index": 1 // exclusive
}

応答の構造

引用が有効な場合、応答には引用付きの複数のテキストブロックが含まれます。

{
  "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
        }
      ]
    }
  ]
}

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

ストリーミング応答では、引用はcontent_block_deltaイベント内のcitations_deltaデルタタイプとして届きます。各デルタには、現在のtextコンテンツブロックのcitationsリストに追加する単一の引用が含まれます。

event: message_start
data: {"type": "message_start", ...}

event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "text_delta", "text": "According to..."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "citations_delta",
                 "citation": {
                     "type": "char_location",
                     "cited_text": "...",
                     "document_index": 0,
                     ...
                 }}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_stop
data: {"type": "message_stop"}

次のステップ

Compatibility