Yerleşik Web Arama

POST https://api.shannon-ai.com/v1/chat/completions

from openai import OpenAI

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.shannon-ai.com/v1")

response = client.chat.completions.create(
    model="shannon-3",
    messages=[{"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}],
    extra_body={"web_search": True},  # a Shannon field, so it goes in extra_body
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const client = new OpenAI({ apiKey: "YOUR_API_KEY", baseURL: "https://api.shannon-ai.com/v1" });

const response = await client.chat.completions.create({
  model: "shannon-3",
  messages: [{ role: "user", content: "What is the weather forecast for Lisbon this weekend?" }],
  web_search: true,
});

console.log(response.choices[0].message.content);

curl https://api.shannon-ai.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "shannon-3",
    "messages": [
      {"role": "user", "content": "What is the weather forecast for Lisbon this weekend?"}
    ],
    "web_search": true
  }'

Yanıt, iki eklemeyle sıradan bir chat completion'dır. Yanıt, arama sonuçlarına köşeli parantez içindeki numaralarla işaret eder, sources her numaranın neyi temsil ettiğini söyler, annotations ise her birinin nerede alıntılandığını işaretler:

{
  "id": "chatcmpl-3e5a7c9b1d2f4a6c8e0b2d4f6a8c1e3b",
  "object": "chat.completion",
  "created": 1791590400,
  "model": "shannon-3",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Saturday in Lisbon is forecast to be sunny with a high near 24 °C [1]. Sunday turns cloudy, with a chance of light rain in the afternoon [2].",
        "reasoning_content": null,
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 66,
              "end_index": 69,
              "url": "https://weather.example/lisbon/weekend",
              "title": "Lisbon weather: weekend outlook"
            }
          },
          {
            "type": "url_citation",
            "url_citation": {
              "start_index": 137,
              "end_index": 140,
              "url": "https://forecast.example/pt/lisbon/sunday",
              "title": "Sunday forecast for Lisbon"
            }
          }
        ]
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 2874,
    "completion_tokens": 41,
    "total_tokens": 2915
  },
  "sources": [
    {
      "index": 1,
      "title": "Lisbon weather: weekend outlook",
      "url": "https://weather.example/lisbon/weekend"
    },
    {
      "index": 2,
      "title": "Sunday forecast for Lisbon",
      "url": "https://forecast.example/pt/lisbon/sunday"
    },
    {
      "index": 3,
      "title": "Portugal: the week ahead",
      "url": "https://news.example/portugal/weather-week"
    }
  ]
}

Aramayı açma

Arama, varsayılan olarak kapalı olan bir istek alanıdır. Bir istek göndermedikçe hiçbir şey aranmaz.

/v1/messages üzerinde alan, gövdenin en üst düzeyinde, model ve messages yanında yer alır:

{
  "model": "shannon-3",
  "web_search": true,
  "messages": [
    {
      "role": "user",
      "content": "What is the weather forecast for Lisbon this weekend?"
    }
  ]
}

Aramalı bir istek ne yapar

• API, son kullanıcı mesajı için web'de arar. Konuşmanın önceki turları aramaya bağlamını verir.
• Arama, web_search: true gönderen her istekte çalışır. Aramanın yapılıp yapılmayacağını model seçmez.
• Sonuçlar numaralı kaynaklar olarak modelin önüne konur ve model yanıtını onlardan yazar.
• Yanıt, arama bittiğinde başlar. Stream edilen bir istek o zamana kadar ne başlık ne olay olarak hiçbir şey göndermez; bu yüzden ilk chunk'tan önce daha uzun bir beklemeye hazır olun.

Yanıt neleri içerir

• Yanıt, kendi uç noktasının olağan biçimindedir. Yanıt choices[0].message.content içindedir (/v1/messages üzerinde bir text bloğu).
• Metin, desteklediği ifadelerden sonra [1] ve [2] gibi işaretler taşıyabilir. Her numara modelin okuduğu sonuçlardan birini temsil eder.
• sources bu sonuçları adlandırır: modele verilen her sonuç için bir girdi, index, title ve url ile. [1] işareti, index değeri 1 olan girdidir. Yanıtın alıntılamadığı sonuçlar da listelenir.
• /v1/chat/completions üzerinde mesajda ayrıca OpenAI biçiminde annotations bulunur: bir işaretin adlandırdığı her kaynak için bir url_citation; içinde url, title, ayrıca işaretin content içindeki konumunu karakter olarak sayan start_index ve end_index (bitiş dahil değildir) yer alır.
• Akışta sources son chunk ile gelir, /v1/messages üzerinde ise message_delta olayıyla gelir. Annotation'lar sondan hemen önceki tek bir chunk içinde, delta.annotations olarak gelir.
• sources yalnızca bu isteğin araması bir şey bulduysa bulunur. Bu alanı olmayan bir yanıt, arama sonuçları olmadan yazılmıştır.

Aramalar nasıl sayılır

Her plan günlük belirli sayıda arama içerir:

• Araması bir şey bulan istek, günlük limitten bir arama kullanır. Hiçbir şey bulamayan arama hiç kullanmaz.
• Sohbet ve API, anahtarın sahibi olan hesabın limitini paylaşır.
• Sayım her gün 00:00 UTC'de yeniden başlar.
• Arama sonuçları isteğin giriş token'larıdır ve istemin geri kalanıyla birlikte faturalandırılır.

Planları karşılaştırın

Günün aramaları bittiğinde

Günün son aramasından sonra web_search: true gönderen bir istek reddedilmez. Aramasız yanıtlanır: durum 200 olur ve yanıtta sources bulunmaz.

Kendi aracınız olarak arama

web_search: true burada anlatılan aramanın tek anahtarıdır. tools içinde tanımladığınız ve web_search adını verdiğiniz bir fonksiyon sizin kendi araçlarınızdan biridir: model bir çağrı döndürür, kodunuz aramayı çalıştırır ve sonucu geri gönderir.

/v1/messages üzerinde web_search_20250305 ya da /v1/responses üzerinde {"type": "web_search"} gibi diğer platformların arama aracı türleri burada arama başlatmaz.

Hatalar

Web araması yeni bir durum kodu ya da hata türü eklemez. Hiçbir şey bulamayan bir arama ya da araması kalmamış bir gün, arama sonucu olmadan normal bir yanıt verir. Diğer her hata, aramasız bir istekteki gibidir. Hata yönetimi