Kutipan

Claude mampu memberikan kutipan terperinci saat menjawab pertanyaan tentang dokumen, membantu Anda melacak dan memverifikasi sumber informasi dalam respons.

Semua model aktif mendukung kutipan, dengan pengecualian Haiku 3.

Berikut adalah contoh cara menggunakan kutipan dengan 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?"
          }
        ]
      }
    ]
  }'

Cara kerja kutipan

Integrasikan kutipan dengan Claude dalam langkah-langkah berikut:

Konten yang dapat dikutip vs tidak dapat dikutip

• Teks yang ditemukan dalam konten source dokumen dapat dikutip.
• title dan context adalah bidang opsional yang akan diteruskan ke model tetapi tidak digunakan menuju konten yang dikutip.
• title dibatasi panjangnya sehingga Anda mungkin menemukan bidang context berguna dalam menyimpan metadata dokumen apa pun sebagai teks atau json yang distring.

Indeks kutipan

• Indeks dokumen diindeks 0 dari daftar semua blok konten dokumen dalam permintaan (mencakup semua pesan).
• Indeks karakter diindeks 0 dengan indeks akhir eksklusif.
• Nomor halaman diindeks 1 dengan nomor halaman akhir eksklusif.
• Indeks blok konten diindeks 0 dengan indeks akhir eksklusif dari daftar content yang disediakan dalam dokumen konten khusus.

Biaya token

• Mengaktifkan kutipan menimbulkan peningkatan kecil dalam token input karena penambahan prompt sistem dan pemotong dokumen.
• Namun, fitur kutipan sangat efisien dengan token keluaran. Di balik layar, model mengeluarkan kutipan dalam format standar yang kemudian diuraikan menjadi teks yang dikutip dan indeks lokasi dokumen. Bidang cited_text disediakan untuk kenyamanan dan tidak dihitung menuju token keluaran.
• Ketika diteruskan kembali dalam giliran percakapan berikutnya, cited_text juga tidak dihitung menuju token input.

Kompatibilitas fitur

Kutipan bekerja bersama dengan fitur API lainnya termasuk prompt caching, token counting dan batch processing.

Menggunakan Prompt Caching dengan Kutipan

Kutipan dan prompt caching dapat digunakan bersama secara efektif.

Blok kutipan yang dihasilkan dalam respons tidak dapat di-cache secara langsung, tetapi dokumen sumber yang direferensikan dapat di-cache. Untuk mengoptimalkan kinerja, terapkan cache_control ke blok konten dokumen tingkat atas Anda.

import anthropic

client = anthropic.Anthropic()

# Konten dokumen panjang (misalnya, dokumentasi teknis)
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # Panjang minimum yang dapat di-cache

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"}  # Cache konten dokumen
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

Dalam contoh ini:

• Konten dokumen di-cache menggunakan cache_control pada blok dokumen
• Kutipan diaktifkan pada dokumen
• Claude dapat menghasilkan respons dengan kutipan sambil mendapat manfaat dari konten dokumen yang di-cache
• Permintaan berikutnya menggunakan dokumen yang sama akan mendapat manfaat dari konten yang di-cache

Jenis Dokumen

Memilih jenis dokumen

Kami mendukung tiga jenis dokumen untuk kutipan. Dokumen dapat disediakan langsung dalam pesan (base64, teks, atau URL) atau diunggah melalui Files API dan direferensikan oleh file_id:

Dokumen teks biasa

Dokumen teks biasa dipotong secara otomatis menjadi kalimat. Anda dapat menyediakannya secara inline atau dengan referensi dengan file_id mereka:

Dokumen PDF

Dokumen PDF dapat disediakan sebagai data yang dikodekan base64 atau oleh file_id. Teks PDF diekstrak dan dipotong menjadi kalimat. Karena kutipan gambar belum didukung, PDF yang merupakan pemindaian dokumen dan tidak berisi teks yang dapat diekstrak tidak akan dapat dikutip.

Dokumen konten khusus

Dokumen konten khusus memberi Anda kontrol atas granularitas kutipan. Tidak ada pemotong tambahan yang dilakukan dan potongan disediakan ke model sesuai dengan blok konten yang disediakan.

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

Struktur Respons

Ketika kutipan diaktifkan, respons mencakup beberapa blok teks dengan kutipan:

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

Dukungan Streaming

Untuk respons streaming, kami telah menambahkan jenis citations_delta yang berisi satu kutipan yang akan ditambahkan ke daftar citations pada blok konten text saat ini.