Hasil pencarian
Dapatkan sitasi alami untuk aplikasi RAG dengan menyediakan hasil pencarian yang disertai atribusi sumber
Penggunaan berbeda menurut produk
search_result dalam hasil alat atau langsung dalam pesan pengguna.user.custom_tool_result, bukan dalam event user.message.Blok konten hasil pencarian memungkinkan Claude mengutip konten Anda sendiri dengan cara yang sama seperti mengutip hasil pencarian web: setiap sitasi membawa sumber dan judul yang Anda berikan. Gunakan blok ini dalam aplikasi “Retrieval-Augmented Generation” (generasi yang diperkaya pengambilan), atau RAG, di mana Claude perlu mengatribusikan jawaban ke dokumen Anda.
Cara kerjanya
Hasil pencarian dapat disediakan dengan dua cara:
- Dari pemanggilan alat: Alat kustom Anda mengembalikan hasil pencarian, yang memungkinkan Anda membangun aplikasi RAG dinamis.
- Sebagai konten tingkat atas: Anda menyediakan hasil pencarian langsung di pesan pengguna untuk konten yang telah diambil sebelumnya atau di-cache.
Dalam kedua kasus, Claude mengutip hasil pencarian secara otomatis ketika sitasi diaktifkan. Tidak diperlukan prompt khusus: ajukan pertanyaan Anda, dan sitasi akan muncul pada blok teks yang menggunakan konten Anda. Namun, jika prompt Anda hanya meminta JSON, respons mungkin berisi sedikit sitasi atau tidak ada sama sekali. Untuk mengekstrak data terstruktur dengan sitasi untuk setiap nilai, lihat Mendapatkan data terstruktur dengan kutipan.
Skema hasil pencarian
Hasil pencarian menggunakan struktur berikut:
{
"type": "search_result",
"source": "https://example.com/article", // Required: Source URL or identifier
"title": "Article Title", // Required: Title of the result
"content": [
// Required: Array of text blocks
{
"type": "text",
"text": "The actual content of the search result..."
}
],
"citations": {
// Optional: Citation configuration
"enabled": true // Enable/disable citations for this result
}
}Field wajib
| Field | Tipe | Deskripsi |
|---|---|---|
type | string | Harus "search_result" |
source | string | Sumber konten. String stabil apa pun dapat digunakan: URL, atau pengidentifikasi internal seperti kb://article-1234 |
title | string | Judul deskriptif untuk hasil pencarian |
content | array | Array blok teks yang berisi konten sebenarnya |
Field opsional
| Field | Tipe | Deskripsi |
|---|---|---|
citations | object | Konfigurasi sitasi dengan field boolean enabled. Sitasi dinonaktifkan secara default; setiap contoh di halaman ini menetapkan "enabled": true secara eksplisit. Semua hasil pencarian dalam satu permintaan harus menggunakan pengaturan yang sama (lihat Kontrol sitasi) |
cache_control | object | Pengaturan kontrol cache (misalnya, {"type": "ephemeral"}) |
Setiap item dalam array content harus berupa blok teks dengan:
type: Harus"text"text: Konten teks sebenarnya (string yang tidak kosong)
Hasil pencarian hanya berisi teks. Gambar dan media lainnya tidak didukung di dalam array content.
Metode 1: Hasil pencarian dari pemanggilan alat
Mengembalikan hasil pencarian dari alat kustom Anda memungkinkan Anda membangun aplikasi RAG dinamis: alat mengambil konten saat runtime, dan Claude mengutipnya dalam respons. Contoh berikut memaksa pemanggilan alat dengan tool_choice, sehingga langkah pengambilan selalu dijalankan setiap kali.
Contoh: Alat basis pengetahuan
from anthropic.types import (
MessageParam,
TextBlockParam,
SearchResultBlockParam,
ToolResultBlockParam,
)
client = Anthropic()
# Definisikan alat pencarian basis pengetahuan
knowledge_base_tool = {
"name": "search_knowledge_base",
"description": "Search the company knowledge base for information",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string", "description": "The search query"}},
"required": ["query"],
},
}
# Fungsi untuk menangani pemanggilan alat
def search_knowledge_base(query):
# Logika pencarian Anda di sini
# Mengembalikan hasil pencarian dalam format yang benar
return [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/product-guide",
title="Product Configuration Guide",
content=[
TextBlockParam(
type="text",
text="To configure the product, navigate to Settings > Configuration. The default timeout is 30 seconds, but can be adjusted between 10-120 seconds based on your needs.",
)
],
citations={"enabled": True},
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/troubleshooting",
title="Troubleshooting Guide",
content=[
TextBlockParam(
type="text",
text="If you encounter timeout errors, first check the configuration settings. Common causes include network latency and incorrect timeout values.",
)
],
citations={"enabled": True},
),
]
# Bangun percakapan dalam sebuah daftar, dimulai dengan pertanyaan pengguna
messages: list[MessageParam] = [
{"role": "user", "content": "How do I configure the timeout settings?"}
]
# Buat pesan dengan alat tersebut
response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
tools=[knowledge_base_tool],
tool_choice={
"type": "tool",
"name": "search_knowledge_base",
"disable_parallel_tool_use": True,
},
messages=messages,
)
# Saat Claude memanggil alat, berikan hasil pencarian.
# Blok tool_use tidak selalu yang pertama: lakukan iterasi untuk menemukannya.
tool_use = next((block for block in response.content if block.type == "tool_use"), None)
if tool_use is not None:
tool_result = search_knowledge_base(tool_use.input["query"])
# Tambahkan giliran Claude, lalu hasil alat, ke percakapan yang sedang berjalan
messages.append({"role": "assistant", "content": response.content})
messages.append(
{
"role": "user",
"content": [
ToolResultBlockParam(
type="tool_result",
tool_use_id=tool_use.id,
content=tool_result, # Search results go here
)
],
}
)
# Kirim kembali hasil alat
final_response = client.messages.create(
model="claude-opus-5",
max_tokens=1024,
messages=messages,
)
print(final_response)Metode 2: Hasil pencarian sebagai konten tingkat atas
Anda juga dapat menyediakan hasil pencarian langsung di pesan pengguna. Ini berguna untuk:
- Konten yang telah diambil sebelumnya dari infrastruktur pencarian Anda
- Hasil pencarian yang di-cache dari kueri sebelumnya
- Konten dari layanan pencarian eksternal
- Pengujian dan pengembangan
Contoh: Hasil pencarian langsung
from anthropic.types import TextBlockParam, SearchResultBlockParam
client = Anthropic()
# Berikan hasil pencarian langsung di pesan pengguna
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/api-reference",
title="API Reference - Authentication",
content=[
TextBlockParam(
type="text",
text="All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.",
)
],
citations={"enabled": True},
),
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/quickstart",
title="Getting Started Guide",
content=[
TextBlockParam(
type="text",
text="To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.",
)
],
citations={"enabled": True},
),
TextBlockParam(
type="text",
text="Based on these search results, how do I authenticate API requests and what are the rate limits?",
),
],
}
],
)
print(response)Respons Claude dengan sitasi
Terlepas dari bagaimana hasil pencarian disediakan, Claude secara otomatis menyertakan sitasi saat menggunakan informasi darinya:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard.",
"citations": [
{
"type": "search_result_location",
"cited_text": "All API requests must include an API key in the Authorization header. Keys can be generated from the dashboard. Rate limits: 1000 requests per hour for standard tier, 10000 for premium.",
"source": "https://docs.company.com/api-reference",
"title": "API Reference - Authentication",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 1
}
]
},
{
"type": "text",
"text": "\n\nTo set this up from scratch, you'll need to "
},
{
"type": "text",
"text": "sign up for an account, generate an API key from the dashboard, install the SDK using `pip install company-sdk`, and initialize the client with your API key.",
"citations": [
{
"type": "search_result_location",
"cited_text": "To get started: 1) Sign up for an account, 2) Generate an API key from the dashboard, 3) Install our SDK using pip install company-sdk, 4) Initialize the client with your API key.",
"source": "https://docs.company.com/quickstart",
"title": "Getting Started Guide",
"search_result_index": 1,
"start_block_index": 0,
"end_block_index": 1
}
]
}
]
}Field sitasi
Setiap sitasi mencakup:
| Field | Tipe | Deskripsi |
|---|---|---|
type | string | Selalu "search_result_location" untuk sitasi hasil pencarian |
source | string | Sumber dari hasil pencarian asli |
title | string atau null | Judul dari hasil pencarian asli |
cited_text | string | Teks lengkap dari blok yang dikutip, digabungkan. Sama dengan isi content[start_block_index:end_block_index] yang digabungkan bersama. Tidak dihitung sebagai token output. |
search_result_index | integer | Indeks berbasis 0 dari hasil pencarian yang dikutip di antara semua blok search_result dalam permintaan, sesuai urutan kemunculannya (di seluruh pesan dan hasil alat). |
start_block_index | integer | Indeks berbasis 0 dari blok pertama yang dikutip dalam array content hasil pencarian. |
end_block_index | integer | Indeks akhir eksklusif dari rentang blok yang dikutip dalam array content hasil pencarian. Selalu lebih besar dari start_block_index. |
Indeks blok mengidentifikasi potongan dari array content hasil pencarian, dan cited_text adalah teks lengkap dari potongan tersebut. Blok teks adalah unit terkecil yang dapat dikutip: Claude mengutip blok utuh, bukan substring di dalam blok. Untuk mendapatkan sitasi yang lebih terperinci, pecah konten hasil pencarian Anda menjadi blok-blok yang lebih kecil (lihat Beberapa blok konten).
Beberapa blok konten
Hasil pencarian dapat berisi beberapa blok teks dalam array content:
{
"type": "search_result",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"content": [
{
"type": "text",
"text": "Authentication: All API requests require an API key."
},
{
"type": "text",
"text": "Rate Limits: The API allows 1000 requests per hour per key."
},
{
"type": "text",
"text": "Error Handling: The API returns standard HTTP status codes."
}
],
"citations": { "enabled": true }
}Sitasi yang merujuk ke blok batas laju terlihat seperti:
{
"type": "search_result_location",
"cited_text": "Rate Limits: The API allows 1000 requests per hour per key.",
"source": "https://docs.company.com/api-guide",
"title": "API Documentation",
"search_result_index": 0,
"start_block_index": 1,
"end_block_index": 2
}Ketika hasil pencarian ini dikutip, start_block_index dan end_block_index mengidentifikasi blok mana yang dicakup oleh sitasi, dan cited_text berisi tepat teks dari blok-blok tersebut. Memecah konten menjadi blok-blok yang lebih kecil dan terfokus memberi Claude batas sitasi yang lebih halus; menggabungkan konten ke dalam satu blok berarti setiap sitasi mengembalikan teks lengkap. Ini adalah model yang sama yang digunakan oleh dokumen konten kustom dalam fitur Kutipan.
Penggunaan lanjutan
Menggabungkan kedua metode
Anda dapat mencampur kedua metode dalam percakapan yang sama. Claude mengutip dari kedua sumber, dan search_result_index menghitung semua blok search_result sesuai urutan permintaan, terlepas dari sumbernya.
Contoh berikut memutar ulang percakapan lengkap. Pesan pengguna pertama membawa hasil pencarian yang telah diambil sebelumnya, giliran asisten memanggil alat basis pengetahuan, dan hasil alat mengembalikan hasil pencarian kedua. Jawaban Claude mengutip kedua sumber:
from anthropic.types import (
SearchResultBlockParam,
TextBlockParam,
ToolResultBlockParam,
ToolUseBlockParam,
)
client = Anthropic()
knowledge_base_tool = {
"name": "search_knowledge_base",
"description": "Search the company knowledge base for information",
"input_schema": {
"type": "object",
"properties": {"query": {"type": "string", "description": "The search query"}},
"required": ["query"],
},
}
# Putar ulang percakapan yang menyediakan hasil pencarian dengan dua cara: pesan
# pengguna pertama membawa hasil yang sudah diambil, dan hasil alat mengembalikan hasil lain
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
tools=[knowledge_base_tool],
messages=[
{
"role": "user",
"content": [
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/overview",
title="Product Overview",
content=[
TextBlockParam(
type="text",
text="Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
)
],
citations={"enabled": True},
),
TextBlockParam(
type="text",
text="What does Acme Dashboard do, and what plans is it available on?",
),
],
},
{
"role": "assistant",
"content": [
TextBlockParam(
type="text", text="Let me check the pricing information."
),
ToolUseBlockParam(
type="tool_use",
id="toolu_01A09q90qw90lq917835lq9",
name="search_knowledge_base",
input={"query": "Acme Dashboard pricing plans"},
),
],
},
{
"role": "user",
"content": [
ToolResultBlockParam(
type="tool_result",
tool_use_id="toolu_01A09q90qw90lq917835lq9",
content=[
SearchResultBlockParam(
type="search_result",
source="https://docs.company.com/pricing",
title="Pricing Plans",
content=[
TextBlockParam(
type="text",
text="Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
)
],
citations={"enabled": True},
)
],
)
],
},
],
)
print(response)Respons mengutip kedua sumber. Hasil yang diambil sebelumnya adalah search_result_index: 0 dan hasil yang dikembalikan alat adalah search_result_index: 1, sesuai dengan urutan kemunculan blok search_result dalam percakapan:
{
"role": "assistant",
"content": [
{
"type": "text",
"text": "Here's what I found about Acme Dashboard:\n\n**What it does:** "
},
{
"type": "text",
"text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
"citations": [
{
"type": "search_result_location",
"cited_text": "Acme Dashboard is a monitoring tool for distributed systems. It supports real-time alerting and custom metric dashboards.",
"source": "https://docs.company.com/overview",
"title": "Product Overview",
"search_result_index": 0,
"start_block_index": 0,
"end_block_index": 1
}
]
},
{
"type": "text",
"text": "\n\n**Available plans:** "
},
{
"type": "text",
"text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
"citations": [
{
"type": "search_result_location",
"cited_text": "Acme Dashboard is available on the Starter plan at $10 per user per month and the Enterprise plan with custom pricing.",
"source": "https://docs.company.com/pricing",
"title": "Pricing Plans",
"search_result_index": 1,
"start_block_index": 0,
"end_block_index": 1
}
]
}
]
}Mencampur dengan tipe konten lain
Dalam pesan pengguna, blok search_result dapat berdampingan dengan blok konten lainnya. Contoh Metode 2 memasangkan hasil pencarian dengan pertanyaan text, dan blok gambar atau dokumen dapat ditambahkan dengan cara yang sama.
Hasil alat lebih ketat: jika ada blok dalam array konten tool_result yang berupa search_result, semua bloknya harus berupa search_result. Mencampur hasil pencarian dengan tipe blok lain dalam hasil alat yang sama akan mengembalikan error validasi. Untuk mengembalikan teks pendukung bersama hasil pencarian dari alat, sertakan teks tersebut sebagai blok teks di dalam salah satu array content hasil pencarian, di mana teks tersebut juga menjadi dapat dikutip.
Kontrol cache
Tambahkan cache_control pada blok hasil pencarian untuk meng-cache-nya agar dapat digunakan kembali di berbagai permintaan. Field ini berada bersama citations pada blok yang sama:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "..." }],
"citations": { "enabled": true },
"cache_control": { "type": "ephemeral" }
}Lihat Caching prompt untuk panjang minimum yang dapat di-cache dan persyaratan lainnya.
Kontrol sitasi
Secara default, sitasi dinonaktifkan untuk hasil pencarian. Anda dapat mengaktifkan sitasi dengan menetapkan konfigurasi citations secara eksplisit:
{
"type": "search_result",
"source": "https://docs.company.com/guide",
"title": "User Guide",
"content": [{ "type": "text", "text": "Important documentation..." }],
"citations": {
"enabled": true // Enable citations for this result
}
}Ketika citations.enabled ditetapkan ke true, Claude melampirkan referensi sitasi ke blok teks yang menggunakan hasil pencarian.
Praktik terbaik
Untuk pencarian berbasis alat (Metode 1)
- Konten dinamis: Gunakan untuk pencarian real-time dan aplikasi RAG dinamis
- Penanganan error: Kembalikan pesan yang sesuai ketika pencarian gagal
- Batas hasil: Kembalikan hanya hasil yang paling relevan untuk menghindari luapan konteks
Untuk pencarian tingkat atas (Metode 2)
- Konten yang diambil sebelumnya: Gunakan ketika Anda sudah memiliki hasil pencarian
- Pemrosesan batch: Gunakan untuk memproses beberapa hasil pencarian sekaligus
- Pengujian: Gunakan untuk menguji perilaku sitasi dengan konten yang sudah diketahui
Praktik terbaik umum
-
Susun hasil secara efektif:
- Gunakan URL sumber yang jelas dan permanen
- Berikan judul yang deskriptif
- Pecah konten panjang menjadi blok teks yang logis untuk memberi Claude batas sitasi yang lebih halus
-
Jaga konsistensi:
- Gunakan format sumber yang konsisten di seluruh aplikasi Anda
- Pastikan judul mencerminkan konten secara akurat
- Jaga format tetap konsisten
-
Tangani error dengan baik: ketika pencarian gagal atau tidak mengembalikan apa pun, kembalikan blok teks biasa yang menjelaskan hasilnya (misalnya,
{"type": "text", "text": "No results found."}) alih-alih memunculkan error: Claude menjelaskan hasil kosong tersebut kepada pengguna, dan percakapan tetap berlanjut.
Batasan
- Hanya konten teks yang didukung dalam hasil pencarian (tanpa gambar atau media lainnya).
- Blok
search_resulthanya dapat muncul di pesan pengguna (termasuk di dalam hasil alat). Pesan asisten dengan hasil pencarian akan ditolak. - Ketika alat pencarian web diaktifkan dalam permintaan yang sama, sitasi harus diaktifkan pada semua blok
search_result.
Langkah selanjutnya
Deteksi dan tangani alasan berhenti berupa penolakan dalam respons streaming, dan coba ulang permintaan yang ditolak pada model cadangan.
Dasarkan respons Claude pada dokumen sumber Anda. Sitasi mengembalikan bagian teks persis yang mendukung setiap klaim, sehingga Anda dapat memverifikasi jawaban dan menampilkan sumber kepada pengguna Anda.
Berikan Claude akses ke konten web terkini dengan sumber yang dikutip, pemfilteran dinamis opsional, dan kontrol domain.
Lihat dokumentasi lengkap Messages API, termasuk tipe-tipe blok konten.
Cache hasil pencarian dengan cache_control untuk mengurangi biaya dan latensi pada permintaan berulang.
Ketersediaan
Claude API
- API
- Messages API
- Managed Agents
- Model
- Semua model
Amazon Bedrock
- API
- Messages API
- Model
- Semua model
Amazon Bedrock (bedrock-runtime)
- API
- Messages API
- Model
- Semua model
Claude Platform on AWS
- API
- Messages API
- Managed Agents
- Model
- Semua model
Claude Models on Google Cloud (Anthropic managed)
- API
- Messages API
- Managed Agents
- Model
- Semua model
Claude Models on Google Cloud (Google managed)
- API
- Messages API
- Model
- Semua model
Microsoft Foundry
- API
- Messages API
- Model
- Semua model
Penanganan data
Ikhtisar penanganan dataEndpoint yang berlaku
/v1/messagesdengan sumbersearch_results
Tidak termasuk Model yang dicakup
Apakah halaman ini membantu?