جستجوی وب داخلی

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
  }'

پاسخ یک chat completion معمولی است با دو افزوده. پاسخ با عددهایی در کروشه به نتایج جستجو اشاره می‌کند، sources می‌گوید هر عدد نماینده چیست و annotations مشخص می‌کند هر کدام کجا ارجاع داده شده است:

{
  "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"
    }
  ]
}

روشن کردن جستجو

جستجو یکی از فیلدهای درخواست است و به‌طور پیش‌فرض خاموش است. تا وقتی درخواستی آن را نفرستد چیزی جستجو نمی‌شود.

در /v1/messages این فیلد در سطح بالای بدنه قرار می‌گیرد، کنار model و messages:

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

درخواست همراه با جستجو چه می‌کند

• API برای آخرین پیام کاربر در وب جستجو می‌کند. نوبت‌های قبلی گفتگو به جستجو زمینه می‌دهند.
• جستجو روی هر درخواستی که web_search: true بفرستد اجرا می‌شود. مدل انتخاب نمی‌کند که جستجو کند یا نه.
• نتایج به‌صورت منابع شماره‌دار جلوی مدل گذاشته می‌شوند و مدل پاسخ خود را از روی آن‌ها می‌نویسد.
• پاسخ وقتی شروع می‌شود که جستجو تمام شده باشد. درخواست stream‌شده تا آن موقع هیچ چیز نمی‌فرستد، نه هدر و نه رویداد، پس برای رسیدن اولین chunk انتظار طولانی‌تری در نظر بگیرید.

پاسخ چه چیزی دارد

• پاسخ شکل معمول endpoint خود را دارد. پاسخ در choices[0].message.content است (در /v1/messages یک بلوک text).
• متن می‌تواند نشانه‌هایی مانند [1] و [2] را بعد از جمله‌هایی که از آن‌ها پشتیبانی می‌کنند داشته باشد. هر عدد نماینده یکی از نتایجی است که مدل خوانده است.
• sources این نتایج را نام می‌برد: برای هر نتیجه‌ای که به مدل داده شده یک ورودی، با index، title و url. نشانه [1] همان ورودی با index برابر 1 است. نتایجی که پاسخ به آن‌ها ارجاع نداده است هم فهرست می‌شوند.
• در /v1/chat/completions پیام همچنین annotations دارد، به شکل OpenAI: برای هر منبعی که یک نشانه نام می‌برد یک url_citation، با url، title و start_index و end_index که جای نشانه در content است و بر حسب نویسه شمرده می‌شود (پایان جزو آن نیست).
• در یک stream، sources همراه آخرین chunk می‌آید و در /v1/messages همراه رویداد message_delta. یادداشت‌های ارجاع در یک chunk درست پیش از آخرین به شکل delta.annotations می‌آیند.
• sources فقط وقتی هست که جستجوی همین درخواست چیزی پیدا کرده باشد. پاسخی که آن را ندارد بدون نتایج جستجو نوشته شده است.

جستجوها چگونه شمرده می‌شوند

هر پلن تعدادی جستجو در روز دارد:

• درخواستی که جستجویش چیزی پیدا کرده یک جستجو از سهمیه آن روز مصرف می‌کند. جستجویی که چیزی پیدا نکند هیچ مصرفی ندارد.
• چت و API سهمیه حسابی را که کلید متعلق به آن است به اشتراک می‌گذارند.
• شمارش هر روز ساعت 00:00 UTC از نو شروع می‌شود.
• نتایج جستجو توکن ورودی درخواست هستند و همراه بقیه پرامپت محاسبه می‌شوند.

مقایسه پلن‌ها

وقتی جستجوهای روز تمام شده‌اند

درخواستی که پس از آخرین جستجوی روز web_search: true بفرستد رد نمی‌شود. بدون جستجو پاسخ داده می‌شود: وضعیت 200 است و پاسخ sources ندارد.

جستجو به‌عنوان ابزار خودتان

web_search: true تنها کلید جستجوی توضیح‌داده‌شده در اینجاست. تابعی که خودتان در tools تعریف کنید و web_search نام بگذارید یکی از ابزارهای خودتان است: مدل یک فراخوانی برمی‌گرداند، و کد شما جستجو را اجرا می‌کند و نتیجه را پس می‌فرستد.

نوع‌های ابزار جستجو در پلتفرم‌های دیگر، مانند web_search_20250305 در /v1/messages یا {"type": "web_search"} در /v1/responses، اینجا جستجو را شروع نمی‌کنند.

خطاها

جستجوی وب کد وضعیت یا نوع خطای جدیدی اضافه نمی‌کند. جستجویی که چیزی پیدا نکند، یا روزی که جستجوی باقی‌مانده ندارد، پاسخ عادی بدون نتایج جستجو می‌دهد. هر خطای دیگر همان است که برای درخواست بدون جستجو هست. مدیریت خطا