ویب تلاش

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

جواب ایک عام چیٹ کمپلیشن ہے جس میں دو اضافے ہیں۔ جواب چوکور قوسین میں نمبروں سے سرچ نتائج کی طرف اشارہ کرتا ہے، 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 بھیجے۔ ماڈل یہ فیصلہ نہیں کرتا کہ سرچ کرنی ہے یا نہیں۔
• نتائج نمبر والے ذرائع کے طور پر ماڈل کے سامنے رکھے جاتے ہیں، اور ماڈل ان سے اپنا جواب لکھتا ہے۔
• سرچ مکمل ہونے پر جواب شروع ہوتا ہے۔ سٹریم کی گئی درخواست تب تک کچھ نہیں بھیجتی، نہ ہیڈرز نہ ایونٹس، اس لیے پہلے chunk سے پہلے زیادہ انتظار کی گنجائش رکھیں۔

جواب میں کیا ہوتا ہے

• جواب اپنے اینڈ پوائنٹ کی معمول کی ساخت میں ہوتا ہے۔ جواب choices[0].message.content میں ہے (/v1/messages پر text بلاک)۔
• متن میں [1] اور [2] جیسے مارکرز ہو سکتے ہیں جو ان بیانات کے بعد آتے ہیں جن کی وہ تائید کرتے ہیں۔ ہر نمبر ان نتائج میں سے ایک کی نمائندگی کرتا ہے جو ماڈل نے پڑھے۔
• sources ان نتائج کے نام بتاتا ہے: ماڈل کو دیے گئے ہر نتیجے کے لیے ایک اندراج، جس میں index، title اور url ہوتے ہیں۔ مارکر [1] وہ اندراج ہے جس کا index 1 ہو۔ جن نتائج کا جواب میں حوالہ نہیں دیا گیا وہ بھی فہرست میں ہوتے ہیں۔
• /v1/chat/completions پر پیغام میں OpenAI کی ساخت میں annotations بھی ہوتے ہیں: مارکر کے بتائے ہوئے ہر ذریعے کے لیے ایک url_citation، جس میں url، title، اور start_index و end_index ہوتے ہیں، یعنی content میں مارکر کی جگہ جو حروف میں گنی جاتی ہے (اختتام شامل نہیں)۔
• سٹریم میں sources آخری چنک کے ساتھ آتا ہے، اور /v1/messages پر message_delta ایونٹ کے ساتھ۔ اینوٹیشنز آخری سے ٹھیک پہلے ایک چنک میں delta.annotations کے طور پر آتی ہیں۔
• sources صرف تب ہوتا ہے جب اس درخواست کی سرچ کو کچھ ملا ہو۔ جس جواب میں یہ نہ ہو وہ سرچ نتائج کے بغیر لکھا گیا تھا۔

سرچز کیسے گنی جاتی ہیں

ہر پلان میں روزانہ کچھ سرچز شامل ہیں:

• جس درخواست کی سرچ میں کچھ ملے وہ دن کے کوٹے میں سے ایک سرچ استعمال کرتی ہے۔ جس سرچ میں کچھ نہ ملے وہ کوئی استعمال نہیں کرتی۔
• چیٹ اور API اس اکاؤنٹ کا کوٹہ مشترکہ استعمال کرتے ہیں جس کی کلید ہے۔
• گنتی ہر روز 00:00 UTC پر دوبارہ شروع ہوتی ہے۔
• سرچ کے نتائج درخواست کے ان پٹ ٹوکنز ہیں اور باقی پرامپٹ کے ساتھ بل ہوتے ہیں۔

پلانز کا موازنہ کریں

جب دن کی سرچز ختم ہو جائیں

جو درخواست دن کی آخری سرچ کے بعد web_search: true بھیجے اسے مسترد نہیں کیا جاتا۔ اس کا جواب سرچ کے بغیر دیا جاتا ہے: سٹیٹس 200 ہے اور جواب میں sources نہیں ہوتا۔

اپنے ٹول کے طور پر سرچ

web_search: true یہاں بیان کی گئی سرچ کا واحد سوئچ ہے۔ جو فنکشن آپ tools میں بنائیں اور جس کا نام web_search رکھیں وہ آپ کا اپنا ٹول ہے: ماڈل کال لوٹاتا ہے، اور آپ کا کوڈ سرچ چلا کر نتیجہ واپس بھیجتا ہے۔

دوسرے پلیٹ فارمز کی سرچ ٹول کی اقسام، جیسے /v1/messages پر web_search_20250305 یا /v1/responses پر {"type": "web_search"}، یہاں سرچ شروع نہیں کرتیں۔

غلطیاں

ویب سرچ نہ کوئی سٹیٹس کوڈ شامل کرتی ہے نہ ایرر کی قسم۔ جس سرچ میں کچھ نہ ملے، یا جس دن سرچز باقی نہ ہوں، اس میں سرچ نتائج کے بغیر عام جواب ملتا ہے۔ باقی ہر غلطی سرچ کے بغیر درخواست جیسی ہی ہے۔ غلطیاں