Kutipan

Claude dapat memberikan kutipan terperinci saat menjawab pertanyaan tentang dokumen, membantu Anda melacak dan memverifikasi sumber di balik setiap respons.

Semua model aktif mendukung kutipan.

Contoh berikut menunjukkan cara mengaktifkan kutipan pada dokumen teks biasa dengan Messages API:

client = anthropic.Anthropic()

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



Cara kerja kutipan

Integrasikan kutipan dengan Claude dalam langkah-langkah berikut:



Konten yang dapat dikutip versus tidak dapat dikutip

• Teks yang ditemukan dalam konten source dokumen dapat dikutip.
• title dan context adalah field opsional yang diteruskan ke model tetapi tidak digunakan sebagai konten yang dikutip.
• title memiliki batasan panjang, sehingga field context berguna untuk menyimpan metadata dokumen sebagai teks atau JSON yang di-stringify.



Indeks kutipan

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



Biaya token

• Mengaktifkan kutipan menyebabkan sedikit peningkatan pada token input karena penambahan prompt sistem dan pemecahan dokumen.
• Namun, fitur kutipan sangat efisien dengan token output. Secara internal, model menghasilkan kutipan dalam format terstandar yang kemudian diurai menjadi teks yang dikutip dan indeks lokasi dokumen. Field cited_text disediakan untuk kemudahan dan tidak dihitung terhadap token output.
• Ketika diteruskan kembali dalam giliran percakapan berikutnya, cited_text juga tidak dihitung terhadap token input.



Kompatibilitas fitur

Kutipan bekerja bersama dengan fitur API lainnya termasuk caching prompt, penghitungan token, dan pemrosesan batch.



Menggunakan caching prompt dengan kutipan

Kutipan dan caching prompt dapat digunakan bersama secara efektif.

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

client = anthropic.Anthropic()

# Konten dokumen panjang (misalnya, dokumentasi teknis)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

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

Dalam contoh ini:

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



Jenis dokumen



Memilih jenis dokumen

Tiga jenis dokumen didukung untuk kutipan. Dokumen dapat disediakan langsung dalam pesan (base64, teks, atau URL) atau diunggah melalui Files API dan direferensikan dengan file_id:



Dokumen teks biasa

Dokumen teks biasa secara otomatis dipecah menjadi kalimat. Anda dapat menyediakannya secara inline atau dengan referensi menggunakan 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 }
}



Dokumen PDF

Dokumen PDF dapat disediakan sebagai data yang dienkode base64, URL, atau dengan file_id. Teks PDF diekstrak dan dipecah menjadi kalimat. Karena kutipan gambar belum didukung, PDF yang merupakan hasil pemindaian dokumen dan tidak berisi teks yang dapat diekstrak tidak dapat dikutip.

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",
    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)



Dokumen konten kustom

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

client = anthropic.Anthropic()

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



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, kutipan tiba sebagai tipe delta citations_delta di dalam event content_block_delta. Setiap delta berisi satu kutipan untuk ditambahkan ke daftar citations pada blok konten text saat ini.



Langkah selanjutnya