Lunos logoLunos
DokumentasiIntegrasi

Pencarian Web (Web Search)

Fitur Pencarian Web (server tool) memungkinkan model AI untuk mengakses informasi terkini dari internet secara real-time. Ketika model memutuskan bahwa informasi terbaru diperlukan untuk menjawab pertanyaan, model akan meminta pencarian web dan kemudian menyusun jawaban yang lebih akurat berdasarkan hasil pencarian tersebut (biasanya disertai sitasi sumber jika tersedia).

Beta: Fitur server tools dan parameter terkait masih dalam tahap beta dan bisa berubah sewaktu-waktu.

Cara Kerja

  1. Request Anda menyertakan tool pencarian web:
    • tools: [{ "type": "web_search" }]
  2. Model mengevaluasi apakah pencarian web dibutuhkan, lalu secara otomatis membuat query pencarian yang relevan.
  3. Lunos meneruskan request ke router, dan router mengeksekusi pencarian menggunakan engine yang telah ditentukan.
  4. Hasil pencarian (berupa URL, judul, dan cuplikan teks) dikirimkan kembali ke model.
  5. Model menyusun jawaban akhir berdasarkan hasil pencarian tersebut. Model juga dapat melakukan pencarian beberapa kali dalam satu request jika diperlukan.

Memulai dengan Cepat (Quick Start)

curl -X POST "https://api.lunos.tech/v1/chat/completions" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [
      { "role": "user", "content": "Apa saja pengumuman AI besar minggu ini?" }
    ],
    "tools": [
      { "type": "web_search" }
    ]
  }'

import requests

url = "https://api.lunos.tech/v1/chat/completions"
headers = {
  "Authorization": "Bearer YOUR_API_KEY",
  "Content-Type": "application/json",
}
payload = {
  "model": "openai/gpt-4o",
  "messages": [
    { "role": "user", "content": "Apa saja pengumuman AI besar minggu ini?" }
  ],
  "tools": [
    { "type": "web_search" }
  ],
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch("https://api.lunos.tech/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "openai/gpt-4o",
    messages: [
      { role: "user", content: "Apa saja pengumuman AI besar minggu ini?" },
    ],
    tools: [{ type: "web_search" }],
  }),
});

const data = await response.json();
console.log(data);

Konfigurasi

Anda dapat menyesuaikan perilaku pencarian dengan menambahkan objek parameters di samping type pada definisi tool.

Contoh:

{
  "tools": [
    {
      "type": "web_search",
      "parameters": {
        "engine": "exa",
        "max_results": 5,
        "max_total_results": 20,
        "search_context_size": "medium",
        "allowed_domains": ["example.com"],
        "excluded_domains": ["reddit.com"]
      }
    }
  ]
}

Parameter yang tersedia:

  • engine (default: auto): Pilihan mesin pencari — auto, native, exa, firecrawl, atau parallel.
  • max_results (default: 5): Jumlah maksimum hasil pencarian per panggilan.
  • max_total_results: Batas total akumulasi hasil dalam satu request (jika model melakukan beberapa kali pencarian).
  • search_context_size (default: medium): Mengatur ukuran konteks cuplikan teks (tergantung engine).
  • allowed_domains: Membatasi hasil pencarian hanya dari domain tertentu.
  • excluded_domains: Mengecualikan hasil dari domain tertentu.

Lokasi Pengguna (Opsional)

Jika engine yang Anda pilih mendukungnya, Anda dapat mengirimkan informasi lokasi perkiraan untuk membuat hasil pencarian yang lebih relevan secara geografis:

{
  "tools": [
    {
      "type": "web_search",
      "parameters": {
        "user_location": {
          "type": "approximate",
          "city": "San Francisco",
          "region": "California",
          "country": "US",
          "timezone": "America/Los_Angeles"
        }
      }
    }
  ]
}

Pemilihan Engine Pencarian

Setiap engine memiliki kapabilitas yang berbeda-beda, seperti dukungan domain filtering atau kontrol ukuran konteks. Berikut pilihan engine yang tersedia:

  • auto (default): Sistem akan memilih pencarian native jika tersedia; jika tidak, akan menggunakan engine berbasis Exa.
  • native: Memaksa penggunaan fitur pencarian web bawaan dari provider model (jika didukung).
  • exa: Menggunakan mesin pencari Exa.
  • firecrawl: Menggunakan mesin pencari Firecrawl (BYOK — Anda perlu menggunakan API key Anda sendiri).
  • parallel: Menggunakan mesin pencari Parallel.

Domain Filtering

Untuk membatasi sumber informasi yang bisa diakses oleh model, konfigurasikan domain filtering:

{
  "type": "web_search",
  "parameters": {
    "allowed_domains": ["arxiv.org", "nature.com"],
    "excluded_domains": ["reddit.com"]
  }
}

Perlu diperhatikan bahwa perilaku domain filtering bergantung pada engine yang digunakan. Jika engine tidak mendukung filter tertentu, Lunos/router mungkin akan menolak request atau mengabaikan field yang tidak didukung.

Mengontrol Total Hasil Pencarian

Jika model melakukan beberapa kali pencarian dalam satu request, gunakan max_total_results untuk membatasi akumulasi jumlah total hasil:

{
  "type": "web_search",
  "parameters": {
    "max_results": 5,
    "max_total_results": 15
  }
}

Setelah batas ini tercapai, pencarian berikutnya dalam request yang sama akan dihentikan secara otomatis dan model akan diberitahu bahwa limit sudah terlampaui.

Penanganan Error

Beberapa kondisi error yang mungkin muncul:

  1. Model tidak mendukung web search berbasis tool — request akan ditolak oleh Lunos.
  2. Tipe tool atau parameter tidak valid — request akan ditolak oleh router.
  3. Engine menolak filter yang tidak dapat diterapkan — perlu penyesuaian parameter.

Jika ini terjadi, coba ganti model yang Anda gunakan atau sesuaikan parameter tool.

Pelacakan Penggunaan (Estimasi)

Jika router menyediakan informasi tambahan, objek usage pada response bisa memuat field khusus terkait server tool (misalnya jumlah total pencarian web yang dilakukan).

Catatan Khusus untuk Lunos

  • Gunakan type: "web_search" di dalam request Lunos.
  • Secara internal, Lunos akan menerjemahkan tipe tool tersebut ke format router yang sesuai secara otomatis.
  • Penggunaan tool pencarian web dapat menambah biaya tambahan di luar biaya token LLM. Pastikan untuk memeriksa tarif engine yang Anda pilih melalui halaman dashboard akun Anda.

Langkah Selanjutnya