የድር ፍለጋ

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 እዩ፣ ክልተ ተወሳኺ ነገራት ዘለዎ። እቲ መልሲ ብቍጽርታት ኣብ ውሽጢ ቅንጥብጣብ (square brackets) ናብ ውጽኢታት ድለያ የመልክት፣ 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"
    }
  ]
}

ድለያ ምብራር

ድለያ field ናይ ጠለብ እዩ፣ ብነባሪ ዝጠፍአ። ጠለብ ዘይልኣኾ እንተ ኾይኑ ዋላ ሓንቲ ኣይድለን።

ኣብ /v1/messages እቲ field ኣብ ላዕለዋይ ደረጃ ናይ body እዩ፣ ጎኒ model ከምኡውን messages፦

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

ብድለያ ዝተላእከ ጠለብ እንታይ ይገብር

• እቲ API ን መልእኽቲ ተጠቃሚ ናይ መወዳእታ ኣብ web ይደሊ። ዝሓለፉ turns ናይ ዕላል ንድለያ context ይህቡ።
• እቲ ድለያ ኣብ ነፍሲ ወከፍ ጠለብ web_search: true ዝልእኽ ይካየድ። እቲ ሞዴል ክደሊ ወይ ኣይደሊ ኣይውስንን።
• እቶም ውጽኢታት ከም ዝተቐጸሩ ምንጭታት ኣብ ቅድሚ እቲ ሞዴል ይቐመጡ፣ እቲ ሞዴል ድማ መልሱ ካብኦም ይጽሕፍ።
• እቲ ምላሽ ድለያ ምስ ተወድአ ይጅምር። ዝውሕዝ ጠለብ ክሳብ ሽዑ ዋላ ሓንቲ ኣይልእኽን፣ headers ወይ events፣ ስለዚ ቅድሚ ቀዳማይ chunk ንነዊሕ ምጽባይ ፍቐድ።

እቲ ምላሽ እንታይ ይሕዝ

• እቲ ምላሽ ልሙድ ቅርጺ endpoint ናቱ ኣለዎ። እቲ መልሲ ኣብ choices[0].message.content (block 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። እቶም annotations ቅድሚ እቲ ናይ መወዳእታ chunk ኣብ ሓደ 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 ናይ ድለያ ናይ ካልኦት ፕላትፎርማት፣ ከም web_search_20250305 ኣብ /v1/messages ወይ {"type": "web_search"} ኣብ /v1/responses፣ ኣብዚ ድለያ ኣይጅምሩን።

ጌጋታት

Web search status code ወይ ዓይነት ጌጋ ኣይውስኽን። ዋላ ሓንቲ ዘይረኸበ ድለያ፣ ወይ ዋላ ሓደ ድለያ ዘይተረፈ መዓልቲ፣ ተራ መልሲ ብዘይ ውጽኢታት ድለያ ይህብ። ኩሉ ካልእ ጌጋ ከም ንጠለብ ብዘይ ድለያ ተመሳሳሊ እዩ። ሓጋይ ኣስተዳደር