بحث ويب مدمج

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. ولا يختار النموذج هل يبحث أم لا.
• توضع النتائج أمام النموذج كمصادر مرقّمة، ويكتب النموذج إجابته منها.
• يبدأ الرد عند انتهاء البحث. والطلب المبثوث لا يرسل شيئاً، لا ترويسات ولا أحداثاً، حتى ذلك الحين، فاحسب حساب انتظار أطول قبل الجزء الأول.

ما يحتويه الرد

• للرد الشكل المعتاد لنقطة نهايته. والإجابة في choices[0].message.content (كتلة text على /v1/messages).
• قد يحمل النص علامات مثل [1] و[2] بعد العبارات التي تدعمها. ويمثل كل رقم إحدى النتائج التي قرأها النموذج.
• يسمّي sources تلك النتائج: مدخل واحد لكل نتيجة أُعطيت للنموذج، مع index وtitle وurl. العلامة [1] هي المدخل الذي له index يساوي 1. وتُسرد أيضاً النتائج التي لا تستشهد بها الإجابة.
• على /v1/chat/completions تحتوي الرسالة أيضاً على annotations بصيغة OpenAI: عنصر url_citation واحد لكل مصدر تسميه علامة، مع url وtitle وstart_index وend_index، وهما موضع العلامة في content محسوباً بالأحرف (النهاية غير مشمولة).
• في البث يأتي sources مع الجزء الأخير، وعلى /v1/messages مع الحدث message_delta. وتأتي علامات الاستشهاد في جزء واحد قبل الأخير مباشرة، بصيغة delta.annotations.
• يوجد sources فقط إذا وجد البحث في هذا الطلب شيئاً. والرد الذي لا يحتوي عليه كُتب بلا نتائج بحث.

كيف تُحتسب عمليات البحث

تتضمن كل خطة عدداً من عمليات البحث في اليوم:

• الطلب الذي وجد بحثه شيئاً يستهلك عملية بحث واحدة من مخصص اليوم. والبحث الذي لم يجد شيئاً لا يستهلك شيئاً.
• تتشارك الدردشة وAPI مخصص الحساب الذي يملك المفتاح.
• يبدأ العدّ من جديد كل يوم عند 00:00 UTC.
• نتائج البحث هي tokens مدخلات للطلب وتُحاسَب مع بقية المطالبة.

قارن بين الخطط

عند استهلاك عمليات البحث في اليوم

الطلب الذي يرسل web_search: true بعد آخر بحث في اليوم لا يُرفض. بل يُجاب عنه بدون بحث: الحالة 200 ولا يحتوي الرد على sources.

البحث كأداة خاصة بك

web_search: true هو المفتاح الوحيد للبحث الموصوف هنا. أما الدالة التي تعرّفها في tools وتسميها web_search فهي إحدى أدواتك الخاصة: يعيد النموذج استدعاءً، ويجري كودك البحث ويرسل النتيجة.

أنواع أدوات البحث في المنصات الأخرى، مثل web_search_20250305 على /v1/messages أو {"type": "web_search"} على /v1/responses، لا تبدأ بحثاً هنا.

الأخطاء

لا يضيف البحث على الويب رمز حالة ولا نوع خطأ. فالبحث الذي لا يجد شيئاً، أو اليوم الذي لم يبق فيه بحث، يعطي إجابة عادية دون نتائج بحث. وكل خطأ آخر هو نفسه كما في الطلب بدون بحث. معالجة الأخطاء