ค้นหาเว็บในตัว

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 ฟิลด์นี้อยู่ที่ระดับบนสุดของ 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 โมเดลไม่ได้เลือกว่าจะค้นหาหรือไม่
• ผลลัพธ์ถูกวางต่อหน้าโมเดลเป็นแหล่งที่มาที่มีหมายเลข และโมเดลเขียนคำตอบจากแหล่งเหล่านั้น
• คำตอบเริ่มเมื่อการค้นหาเสร็จ คำขอแบบสตรีมไม่ส่งอะไรเลย ทั้งเฮดเดอร์และ event จนกว่าจะถึงตอนนั้น จึงควรเผื่อเวลารอ 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 นับเป็นตัวอักษร (ไม่รวมตำแหน่งสิ้นสุด)
• ในสตรีม sources มาพร้อมกับ chunk สุดท้าย และบน /v1/messages มาพร้อมกับอีเวนต์ message_delta ส่วน annotations มาใน chunk เดียวก่อน chunk สุดท้าย ในรูป delta.annotations
• sources จะมีเฉพาะเมื่อการค้นหาของคำขอนี้พบผลลัพธ์ คำตอบที่ไม่มีรายการนี้ถูกเขียนโดยไม่มีผลการค้นหา

การนับการค้นหา

ทุกแผนมีจำนวนการค้นหาต่อวัน:

• คำขอที่การค้นหาพบผลลัพธ์ใช้โควตาการค้นหาของวันหนึ่งครั้ง การค้นหาที่ไม่พบอะไรไม่ใช้โควตา
• แชตและ API ใช้โควตาร่วมกันของบัญชีที่เป็นเจ้าของคีย์
• การนับเริ่มใหม่ทุกวันเวลา 00:00 UTC
• ผลการค้นหาเป็น input tokens ของคำขอและถูกคิดเงินพร้อมกับ prompt ส่วนที่เหลือ

เปรียบเทียบแผน

เมื่อการค้นหาของวันใช้หมด

คำขอที่ส่ง web_search: true หลังการค้นหาครั้งสุดท้ายของวันจะไม่ถูกปฏิเสธ แต่จะถูกตอบโดยไม่มีการค้นหา: สถานะเป็น 200 และคำตอบไม่มี sources

การค้นหาเป็น tool ของคุณเอง

web_search: true เป็นสวิตช์เดียวของการค้นหาที่อธิบายไว้ที่นี่ ฟังก์ชันที่คุณนิยามใน tools และตั้งชื่อว่า web_search เป็น tool ของคุณเอง: โมเดลส่งการเรียกกลับมา แล้วโค้ดของคุณรันการค้นหาและส่งผลลัพธ์กลับ

tool ค้นหาชนิดของแพลตฟอร์มอื่น เช่น web_search_20250305 บน /v1/messages หรือ {"type": "web_search"} บน /v1/responses จะไม่เริ่มการค้นหาที่นี่

ข้อผิดพลาด

การค้นหาเว็บไม่เพิ่มรหัสสถานะและประเภทข้อผิดพลาด การค้นหาที่ไม่พบอะไร หรือวันที่ไม่มีการค้นหาเหลือ จะให้คำตอบปกติที่ไม่มีผลการค้นหา ข้อผิดพลาดอื่นทุกอย่างเหมือนกับคำขอที่ไม่มีการค้นหา การจัดการข้อผิดพลาด