Claude Platform Docs
PesanKemampuan model

Kutipan

Dasarkan respons Claude pada dokumen sumber Anda. Kutipan mengembalikan bagian teks yang tepat yang mendukung setiap klaim, sehingga Anda dapat memverifikasi jawaban dan menampilkan sumber kepada pengguna Anda.

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-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:

  1. Sediakan dokumen dan aktifkan kutipan

    • Sertakan dokumen dalam salah satu format yang didukung: dokumen PDF, teks biasa, atau konten kustom.
    • Atur citations.enabled=true pada setiap dokumen Anda. Saat ini, kutipan harus diaktifkan pada semua atau tidak sama sekali dari dokumen dalam sebuah permintaan.
    • Hanya kutipan teks yang saat ini didukung. Kutipan gambar belum memungkinkan.
  2. Dokumen diproses

    • Konten dokumen “dipotong” (chunked) untuk menentukan granularitas minimum dari kutipan yang mungkin. Misalnya, pemotongan kalimat memungkinkan Claude mengutip satu kalimat atau merangkai beberapa kalimat berurutan untuk mengutip paragraf atau bagian yang lebih panjang.
      • Untuk PDF: Teks diekstrak seperti yang dijelaskan dalam dukungan PDF dan konten dipotong menjadi kalimat. Mengutip gambar dari PDF saat ini tidak didukung.
      • Untuk dokumen teks biasa: Konten dipotong menjadi kalimat yang dapat dikutip.
      • Untuk dokumen konten kustom: Blok konten yang Anda sediakan digunakan apa adanya dan tidak ada pemotongan lebih lanjut yang dilakukan.
  3. Claude memberikan respons yang dikutip

    • Respons kini dapat menyertakan beberapa blok teks di mana setiap blok teks dapat berisi klaim yang dibuat Claude dan daftar kutipan yang mendukung klaim tersebut.
    • Kutipan merujuk ke lokasi tertentu dalam dokumen sumber. Format kutipan ini bergantung pada jenis dokumen yang dikutip.
      • Untuk PDF: Kutipan mencakup rentang nomor halaman (diindeks mulai dari 1).
      • Untuk dokumen teks biasa: Kutipan mencakup rentang indeks karakter (diindeks mulai dari 0).
      • Untuk dokumen konten kustom: Kutipan mencakup rentang indeks blok konten (diindeks mulai dari 0) yang sesuai dengan daftar konten asli yang disediakan.
    • Indeks dokumen disediakan untuk menunjukkan sumber referensi dan diindeks mulai dari 0 sesuai dengan daftar semua dokumen dalam permintaan asli Anda.

Konten yang dapat dikutip versus tidak dapat dikutip

  • Teks yang ditemukan dalam konten source dokumen dapat dikutip.
  • title dan context adalah bidang opsional yang diteruskan ke model tetapi tidak digunakan untuk konten yang dikutip.
  • title terbatas panjangnya, sehingga bidang context berguna untuk menyimpan metadata dokumen sebagai teks atau JSON yang distringifikasi.

Indeks kutipan

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

Biaya token

  • Mengaktifkan kutipan menyebabkan sedikit peningkatan token input karena penambahan prompt sistem dan pemotongan dokumen.
  • Namun, fitur kutipan sangat efisien dalam hal token output. Secara internal, model menghasilkan kutipan dalam format standar, dan kutipan tersebut kemudian diurai menjadi teks yang dikutip dan indeks lokasi dokumen. Bidang cited_text disediakan untuk kemudahan dan tidak dihitung sebagai 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.

Mendapatkan data terstruktur dengan kutipan

Untuk mendapatkan kutipan bagi setiap nilai yang diekstrak, minta Claude untuk menjawab dengan satu baris per bidang. Kemudian, uraikan baris-baris tersebut menjadi data terstruktur di kode Anda.

Hindari prompt pengguna atau prompt sistem yang hanya meminta JSON, seperti “Kembalikan hanya objek JSON, tanpa teks lain.” Permintaan dengan prompt seperti itu akan berhasil, tetapi respons mungkin hanya berisi sedikit kutipan atau bahkan tidak ada sama sekali.

Prompt berikut meminta dua bidang dari dokumen teks biasa dalam contoh di bagian atas halaman ini. Kirimkan prompt ini sebagai pengganti pertanyaan dalam contoh tersebut:

Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

Dalam respons berikut, setiap nilai memiliki kutipannya sendiri:

{
  "content": [
    { "type": "text", "text": "grass_color: " },
    {
      "type": "text",
      "text": "green",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The grass is green. ",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 0,
          "end_char_index": 20
        }
      ]
    },
    { "type": "text", "text": "\nsky_color: " },
    {
      "type": "text",
      "text": "blue",
      "citations": [
        {
          "type": "char_location",
          "cited_text": "The sky is blue.",
          "document_index": 0,
          "document_title": "My Document",
          "start_char_index": 20,
          "end_char_index": 36
        }
      ]
    }
  ]
}

Untuk mengurai respons, ikuti langkah-langkah berikut:

  1. Baca blok text secara berurutan, dan tambahkan teks setiap blok ke baris saat ini. Mulai baris baru di setiap karakter baris baru.
  2. Lampirkan citations dari setiap blok ke setiap baris yang berisi bagian dari teksnya. Blok yang dikutip dapat berisi hanya sebuah nilai, seperti dalam contoh ini, atau satu baris penuh.
  3. Lewati baris yang tidak memiliki titik dua. Pisahkan setiap baris yang tersisa pada titik dua pertamanya menjadi nama bidang dan nilai, lalu hapus spasi di awal dan akhir keduanya. Lewati baris yang namanya bukan salah satu bidang Anda, seperti catatan penutup.
  4. Periksa bahwa setiap bidang memiliki nilai dan setidaknya satu kutipan. API tidak menjamin satu pun dari keduanya.

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-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 memanfaatkan konten dokumen yang di-cache.
  • Permintaan berikutnya yang menggunakan dokumen yang sama memanfaatkan 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 dirujuk dengan file_id:

JenisTerbaik untukPemotonganFormat kutipan
Teks biasaDokumen teks sederhana, prosaKalimatIndeks karakter (diindeks mulai dari 0)
PDFFile PDF dengan konten teksKalimatNomor halaman (diindeks mulai dari 1)
Konten kustomDaftar, transkrip, pemformatan khusus, kutipan yang lebih granularTidak ada pemotongan tambahanIndeks blok (diindeks mulai dari 0)

Dokumen teks biasa

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

Contoh pengantar di bagian atas halaman ini menunjukkan permintaan teks biasa yang lengkap di setiap SDK. Blok dokumen menggunakan sumber text:

{
  "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 diberikan sebagai data yang dienkode base64, sebagai URL, atau dengan file_id. Teks PDF diekstrak dan dipotong menjadi kalimat. Karena kutipan gambar belum didukung, PDF yang merupakan hasil pindaian 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-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 pemotongan 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-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

Pelajari alur event dan tipe delta blok konten lainnya yang tiba bersama citations_delta.

Teruskan hasil pencarian dari pipeline RAG Anda sebagai blok konten kelas satu dengan dukungan kutipan bawaan.

Pelajari bagaimana Claude mengekstrak teks dari PDF dan bagaimana kutipan berbasis halaman dipetakan kembali ke file sumber Anda.

Unggah dokumen sekali dan rujuk dengan file_id di beberapa permintaan kutipan.

Ketersediaan

Kutipan
API
  • Messages API
  • Managed Agents Tidak didukung
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages
Retensi data nolLayak

Tidak termasuk Model yang dicakup

HIPAALayak

Apakah halaman ini membantu?