Claudeは文書に関する質問に答える際に詳細な引用を提供することができ、回答における情報源の追跡と検証を支援します。

引用機能は現在、Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.7、Claude Sonnet 3.5(新版)、およびHaiku 3.5で利用可能です。

Claude Sonnet 3.7での引用

Claude Sonnet 3.7は、ユーザーからのより明示的な指示なしには、他のClaudeモデルと比較して引用を行う可能性が低い場合があります。Claude Sonnet 3.7で引用を使用する際は、userターンに「回答を裏付けるために引用を使用してください。」などの追加指示を含めることをお勧めします。

また、モデルが回答を構造化するよう求められた場合、その形式内で引用を使用するよう明示的に指示されない限り、引用を使用する可能性は低いことも観察されています。例えば、モデルが回答でタグを使用するよう求められた場合、「内でも常に回答で引用を使用してください。」のような指示を追加する必要があります。

引用機能に関するフィードバックやご提案は、このフォームを使用してお聞かせください。

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-20250514",
    "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に引用を統合します:

1

文書を提供し、引用を有効にする

  • サポートされている形式のいずれかで文書を含める:PDFプレーンテキスト、またはカスタムコンテンツ文書
  • 各文書でcitations.enabled=trueを設定します。現在、引用はリクエスト内のすべての文書で有効にするか、すべてで無効にするかのいずれかである必要があります。
  • 現在はテキスト引用のみがサポートされており、画像引用はまだ利用できないことにご注意ください。
2

文書が処理される

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

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

  • 回答には、Claudeが主張している内容とその主張を支持する引用のリストを含む複数のテキストブロックが含まれる場合があります。
  • 引用はソース文書内の特定の場所を参照します。これらの引用の形式は、引用される文書の種類によって異なります。
    • PDFの場合: 引用にはページ番号範囲(1インデックス)が含まれます。
    • プレーンテキスト文書の場合: 引用には文字インデックス範囲(0インデックス)が含まれます。
    • カスタムコンテンツ文書の場合: 引用には、提供された元のコンテンツリストに対応するコンテンツブロックインデックス範囲(0インデックス)が含まれます。
  • 文書インデックスは参照ソースを示すために提供され、元のリクエスト内のすべての文書のリストに従って0インデックスです。

自動チャンク化 vs カスタムコンテンツ

デフォルトでは、プレーンテキストとPDF文書は自動的に文単位でチャンク化されます。引用の粒度をより細かく制御する必要がある場合(例:箇条書きや転写記録)は、代わりにカスタムコンテンツ文書を使用してください。詳細については文書タイプを参照してください。

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

引用可能コンテンツ vs 引用不可能コンテンツ

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

引用インデックス

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

トークンコスト

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

機能の互換性

引用は、プロンプトキャッシュトークンカウントバッチ処理を含む他のAPI機能と連携して動作します。

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

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

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

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

PDF文書

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

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data
    },
    "title": "Document Title", # オプション
    "context": "Context about the document that will not be cited from", # オプション
    "citations": {"enabled": True}
}

カスタムコンテンツ文書

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

{
    "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タイプを追加しました。