Hasil pencarian

Blok konten hasil pencarian memungkinkan sitasi alami dengan atribusi sumber yang tepat, menghadirkan sitasi berkualitas setara pencarian web ke aplikasi kustom Anda. Fitur ini sangat berguna untuk aplikasi "Retrieval-Augmented Generation" (generasi yang diperkaya pengambilan), atau RAG, di mana Anda membutuhkan Claude untuk mengutip sumber secara akurat.

Fitur hasil pencarian tersedia pada model-model berikut:

• Claude Opus 4.8 (claude-opus-4-8)
• Claude Opus 4.7 (claude-opus-4-7)
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 5 (claude-sonnet-5)
• Claude Sonnet 4.6 (claude-sonnet-4-6)
• Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Claude Opus 4.5 (claude-opus-4-5-20251101)
• Claude Opus 4.1 (tidak digunakan lagi) (claude-opus-4-1-20250805)
• Claude Opus 4 (dihentikan, kecuali di Google Cloud) (claude-opus-4-20250514)
• Claude Sonnet 4 (dihentikan, kecuali di Bedrock dan Google Cloud) (claude-sonnet-4-20250514)
• Claude Haiku 4.5 (claude-haiku-4-5-20251001)
• Claude Haiku 3.5 (dihentikan, kecuali di Bedrock dan Google Cloud) (claude-3-5-haiku-20241022)



Manfaat utama

• Sitasi alami: Mencapai kualitas sitasi yang sama seperti pencarian web untuk konten apa pun
• Integrasi fleksibel: Gunakan dalam hasil pengembalian alat untuk RAG dinamis atau sebagai konten tingkat atas untuk data yang telah diambil sebelumnya
• Atribusi sumber yang tepat: Setiap hasil menyertakan informasi sumber dan judul untuk atribusi yang jelas
• Tidak perlu solusi alternatif berbasis dokumen: Menghilangkan kebutuhan akan solusi alternatif berbasis dokumen
• Format sitasi yang konsisten: Sesuai dengan kualitas dan format sitasi dari fungsionalitas pencarian web Claude



Cara kerjanya

Hasil pencarian dapat disediakan dengan dua cara:

1. Dari pemanggilan alat: Alat kustom Anda mengembalikan hasil pencarian, memungkinkan aplikasi RAG dinamis
2. Sebagai konten tingkat atas: Anda menyediakan hasil pencarian secara langsung dalam pesan pengguna untuk konten yang telah diambil sebelumnya atau di-cache

Dalam kedua kasus tersebut, Claude dapat secara otomatis mengutip informasi dari hasil pencarian dengan atribusi sumber yang tepat.



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 opsional

Setiap item dalam array content harus berupa blok teks dengan:

• type: Harus berupa "text"
• text: Konten teks sebenarnya (string yang tidak kosong)



Metode 1: Hasil pencarian dari pemanggilan alat

Kasus penggunaan yang paling kuat adalah mengembalikan hasil pencarian dari alat kustom Anda. Ini memungkinkan aplikasi RAG dinamis di mana alat mengambil dan mengembalikan konten yang relevan dengan sitasi otomatis.



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 panggilan 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},
        ),
    ]


# Buat pesan dengan alat tersebut
response = client.messages.create(
    model="claude-opus-4-8",  # Works with all supported models
    max_tokens=1024,
    tools=[knowledge_base_tool],
    messages=[
        MessageParam(role="user", content="How do I configure the timeout settings?")
    ],
)

# Ketika Claude memanggil alat, berikan hasil pencarian
if response.content[0].type == "tool_use":
    tool_result = search_knowledge_base(response.content[0].input["query"])

    # Kirim kembali hasil alat
    final_response = client.messages.create(
        model="claude-opus-4-8",  # Works with all supported models
        max_tokens=1024,
        messages=[
            MessageParam(
                role="user", content="How do I configure the timeout settings?"
            ),
            MessageParam(role="assistant", content=response.content),
            MessageParam(
                role="user",
                content=[
                    ToolResultBlockParam(
                        type="tool_result",
                        tool_use_id=response.content[0].id,
                        content=tool_result,  # Search results go here
                    )
                ],
            ),
        ],
    )



Metode 2: Hasil pencarian sebagai konten tingkat atas

Anda juga dapat menyediakan hasil pencarian secara langsung dalam 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 MessageParam, TextBlockParam, SearchResultBlockParam

client = Anthropic()

# Berikan hasil pencarian langsung dalam pesan pengguna
response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        MessageParam(
            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 dari hasil tersebut:

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

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 secara utuh, bukan substring di dalam sebuah 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."
    }
  ]
}

Sitasi yang merujuk pada blok batas laju terlihat seperti ini:

{
  "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 persis teks dari blok-blok tersebut. Memecah konten menjadi blok-blok yang lebih kecil dan terfokus memberi Claude batas sitasi yang lebih halus; menggabungkan konten menjadi satu blok berarti setiap sitasi mengembalikan teks lengkap. Ini adalah model yang sama yang digunakan oleh dokumen konten kustom dalam fitur Citations.



Penggunaan lanjutan



Menggabungkan kedua metode

Anda dapat menggunakan hasil pencarian berbasis alat dan tingkat atas dalam percakapan yang sama:

from anthropic.types import MessageParam, SearchResultBlockParam, TextBlockParam

# Pesan pertama dengan hasil pencarian tingkat atas
messages = [
    MessageParam(
        role="user",
        content=[
            SearchResultBlockParam(
                type="search_result",
                source="https://docs.company.com/overview",
                title="Product Overview",
                content=[
                    TextBlockParam(
                        type="text", text="Our product helps teams collaborate..."
                    )
                ],
                citations={"enabled": True},
            ),
            TextBlockParam(
                type="text",
                text="Tell me about this product and search for pricing information",
            ),
        ],
    )
]

# Claude mungkin merespons dan memanggil alat untuk mencari harga
# Kemudian Anda memberikan hasil alat dengan lebih banyak hasil pencarian



Menggabungkan dengan tipe konten lain

Kedua metode mendukung pencampuran hasil pencarian dengan konten lain:

from anthropic.types import SearchResultBlockParam, TextBlockParam

# Dalam hasil alat
tool_result = [
    SearchResultBlockParam(
        type="search_result",
        source="https://docs.company.com/guide",
        title="User Guide",
        content=[TextBlockParam(type="text", text="Configuration details...")],
        citations={"enabled": True},
    ),
    TextBlockParam(
        type="text", text="Additional context: This applies to version 2.0 and later."
    ),
]

# Dalam konten tingkat atas
user_content = [
    SearchResultBlockParam(
        type="search_result",
        source="https://research.com/paper",
        title="Research Paper",
        content=[TextBlockParam(type="text", text="Key findings...")],
        citations={"enabled": True},
    ),
    {
        "type": "image",
        "source": {"type": "url", "url": "https://example.com/chart.png"},
    },
    TextBlockParam(
        type="text", text="How does the chart relate to the research findings?"
    ),
]



Kontrol cache

Tambahkan kontrol cache untuk performa yang lebih baik:

{
  "type": "search_result",
  "source": "https://docs.company.com/guide",
  "title": "User Guide",
  "content": [{ "type": "text", "text": "..." }],
  "cache_control": {
    "type": "ephemeral"
  }
}



Kontrol sitasi

Secara default, sitasi dinonaktifkan untuk hasil pencarian. Anda dapat mengaktifkan sitasi dengan secara eksplisit mengatur konfigurasi citations:

{
  "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 diatur ke true, Claude menyertakan referensi sitasi saat menggunakan informasi dari hasil pencarian. Ini memungkinkan:

• Sitasi alami untuk aplikasi RAG kustom Anda
• Atribusi sumber saat berinteraksi dengan basis pengetahuan proprietary
• Sitasi berkualitas setara pencarian web untuk alat kustom apa pun yang mengembalikan 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 konteks yang meluap



Untuk pencarian tingkat atas (Metode 2)

• Konten yang telah diambil sebelumnya: Gunakan ketika Anda sudah memiliki hasil pencarian
• Pemrosesan batch: Ideal untuk memproses beberapa hasil pencarian sekaligus
• Pengujian: Sangat baik untuk menguji perilaku sitasi dengan konten yang diketahui



Praktik terbaik umum

1. Strukturkan hasil secara efektif:

   • Gunakan URL sumber yang jelas dan permanen
   • Sediakan judul yang deskriptif
   • Pecah konten panjang menjadi blok teks yang logis untuk memberi Claude batas sitasi yang lebih halus

2. Pertahankan konsistensi:

   • Gunakan format sumber yang konsisten di seluruh aplikasi Anda
   • Pastikan judul secara akurat mencerminkan konten
   • Jaga format tetap konsisten

3. Tangani error dengan baik:

   def search_with_fallback(query):
       try:
           results = perform_search(query)
           if not results:
               return {"type": "text", "text": "No results found."}
           return format_as_search_results(results)
       except Exception as e:
           return {"type": "text", "text": f"Search error: {str(e)}"}

   



Batasan

• Blok konten hasil pencarian tersedia di Claude API, Amazon Bedrock, dan Google Cloud
• Hanya konten teks yang didukung dalam hasil pencarian (tidak ada gambar atau media lainnya)
• Array content harus berisi setidaknya satu blok teks



Langkah selanjutnya