የተገናኘ ድር ፍለጋ

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

ፍለጋን ማብራት

ፍለጋ የጥያቄ መስክ ነው፣ በdefault ጠፍቷል። ጥያቄ እስካልላከው ድረስ ምንም አይፈለግም።

በ/v1/messages ላይ መስኩ በbody የላይኛው ደረጃ፣ ከ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 ጥያቄ እስከዚያ ድረስ ምንም አይልክም፣ headers ወይም events አይደሉም፣ ስለዚህ ከመጀመሪያው chunk በፊት ረዘም ያለ ጥበቃ ይጠብቁ።

ምላሹ የሚይዘው

• ምላሹ የendpoint ውን የተለመደ ቅርጽ አለው። መልሱ በchoices[0].message.content ውስጥ ነው (በ/v1/messages ላይ text block)።
• ጽሑፉ ከሚደግፏቸው ዓረፍተ ነገሮች በኋላ እንደ [1] እና [2] ያሉ ምልክቶችን ሊይዝ ይችላል። እያንዳንዱ ቁጥር ሞዴሉ ካነበባቸው ውጤቶች አንዱን ይወክላል።
• sources እነዚያን ውጤቶች ይሰይማል፦ ለሞዴሉ ለተሰጠው እያንዳንዱ ውጤት አንድ ግቤት፣ ከindex፣ title እና url ጋር። ምልክቱ [1] index 1 ያለው ግቤት ነው። መልሱ ያልጠቀሳቸው ውጤቶችም ተዘርዝረዋል።
• በ/v1/chat/completions ላይ መልዕክቱ በOpenAI ቅርጽ annotations ደግሞ አለው፦ ምልክት ለሰየመው እያንዳንዱ ምንጭ አንድ url_citation፣ ከurl፣ title፣ እንዲሁም ከstart_index እና end_index ጋር፤ እነዚህም የምልክቱ አቀማመጥ በcontent ውስጥ በቁምፊዎች ተቆጥሮ ናቸው (መጨረሻው አይካተትም)።
• በstream ውስጥ sources ከመጨረሻው chunk ጋር ይመጣል፣ በ/v1/messages ላይ ደግሞ ከmessage_delta ክስተት ጋር። annotations ከመጨረሻው በፊት ባለው በአንድ chunk ውስጥ እንደ delta.annotations ይመጣሉ።
• sources የሚኖረው የዚህ ጥያቄ ፍለጋ አንድ ነገር ካገኘ ብቻ ነው። ያለ እሱ ምላሽ ያለ ፍለጋ ውጤቶች ተጽፏል።

ፍለጋዎች እንዴት ይቆጠራሉ

እያንዳንዱ ዕቅድ በቀን የተወሰነ የፍለጋ ብዛት ያካትታል፦

• ፍለጋው አንድ ነገር ያገኘ ጥያቄ ከቀኑ መጠን አንድ ፍለጋ ይጠቀማል። ምንም ያላገኘ ፍለጋ ምንም አይጠቀምም።
• Chat እና API የቁልፉ ባለቤት የሆነውን መለያ መጠን ይጋራሉ።
• ቆጠራው በየቀኑ በ00:00 UTC እንደገና ይጀምራል።
• የፍለጋ ውጤቶቹ የጥያቄው input tokens ናቸው እና ከቀሪው prompt ጋር ይከፈላሉ።

ዕቅዶችን ያወዳድሩ

የቀኑ ፍለጋዎች ሲያልቁ

የቀኑ የመጨረሻ ፍለጋ ከተጠቀመ በኋላ web_search: true የሚልክ ጥያቄ አይከለከልም። ያለ ፍለጋ ይመለሳል፦ status 200 ነው እና ምላሹ sources የለውም።

ፍለጋ እንደ የራስዎ tool

web_search: true እዚህ የተገለጸው ፍለጋ ብቸኛው መቀየሪያ ነው። በtools ውስጥ የሚገልጹት እና web_search ብለው የሰየሙት function ከእርስዎ የራስ tools አንዱ ነው፦ ሞዴሉ ጥሪ ይመልሳል፣ ኮድዎም ፍለጋውን ያስኬዳል እና ውጤቱን መልሶ ይልካል።

የሌሎች መድረኮች የፍለጋ tool አይነቶች፣ ለምሳሌ በ/v1/messages ላይ web_search_20250305 ወይም በ/v1/responses ላይ {"type": "web_search"}፣ እዚህ ፍለጋ አይጀምሩም።

ስህተቶች

የድር ፍለጋ status ኮድ ወይም የስህተት አይነት አይጨምርም። ምንም የማያገኝ ፍለጋ፣ ወይም ፍለጋ የሌለበት ቀን፣ ያለ ፍለጋ ውጤቶች መደበኛ መልስ ይሰጣል። ሌላ ማንኛውም ስህተት ያለ ፍለጋ ለሚደረግ ጥያቄ ካለው ጋር ተመሳሳይ ነው። ስህተት አስተዳደር