חיפוש ווב מובנה

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. המודל אינו בוחר אם לחפש.
• התוצאות מונחות לפני המודל כמקורות ממוספרים, והמודל כותב את תשובתו מתוכן.
• התשובה מתחילה כשהחיפוש הסתיים. בקשה ב-streaming אינה שולחת דבר, לא כותרות ולא אירועים, עד אז, ולכן הניחו המתנה ארוכה יותר לפני ה-chunk הראשון.

מה התשובה מכילה

• לתשובה יש הצורה הרגילה של ה-endpoint שלה. התשובה נמצאת ב-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 נספר בתווים (הסוף אינו נכלל).
• ב-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, אינם מתחילים חיפוש כאן.

שגיאות

חיפוש ברשת אינו מוסיף קוד סטטוס ואינו מוסיף סוג שגיאה. חיפוש שלא מוצא דבר, או יום בלי חיפושים שנותרו, נותן תשובה רגילה בלי תוצאות חיפוש. כל שגיאה אחרת זהה לזו של בקשה בלי חיפוש. טיפול בשגיאות