Tìm kiếm web tích hợp

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
  }'

Phản hồi là một chat completion bình thường với hai phần bổ sung. Câu trả lời dẫn tới các kết quả tìm kiếm bằng các số trong dấu ngoặc vuông, sources cho biết mỗi số tương ứng với gì, và annotations đánh dấu vị trí mỗi nguồn được trích dẫn:

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

Bật tìm kiếm

Tìm kiếm là một trường của yêu cầu, mặc định tắt. Không có gì được tìm kiếm trừ khi yêu cầu gửi nó.

Trên /v1/messages, trường này nằm ở cấp cao nhất của nội dung, cạnh model và messages:

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

Yêu cầu có tìm kiếm làm gì

• API tìm kiếm trên web theo tin nhắn người dùng cuối cùng. Các lượt trước của cuộc hội thoại cung cấp ngữ cảnh cho việc tìm kiếm.
• Tìm kiếm chạy trên mọi yêu cầu gửi web_search: true. Model không chọn có tìm kiếm hay không.
• Kết quả được đặt trước model dưới dạng các nguồn có đánh số, và model viết câu trả lời từ chúng.
• Phản hồi bắt đầu khi tìm kiếm xong. Yêu cầu streaming không gửi gì, cả header lẫn sự kiện, cho đến lúc đó, nên hãy dự trù thời gian chờ lâu hơn trước chunk đầu tiên.

Phản hồi chứa gì

• Phản hồi có dạng thông thường của endpoint. Câu trả lời nằm trong choices[0].message.content (một khối text trên /v1/messages).
• Văn bản có thể mang các dấu như [1] và [2] sau những câu khẳng định mà chúng hỗ trợ. Mỗi số tương ứng với một trong các kết quả model đã đọc.
• sources nêu tên các kết quả đó: một mục cho mỗi kết quả đã đưa cho model, gồm index, title và url. Dấu [1] là mục có index bằng 1. Những kết quả mà câu trả lời không trích dẫn cũng được liệt kê.
• Trên /v1/chat/completions, message còn có annotations theo dạng của OpenAI: một url_citation cho mỗi nguồn mà một dấu nêu tên, gồm url, title, cùng start_index và end_index là vị trí của dấu trong content, đếm theo ký tự (không tính vị trí kết thúc).
• Trong stream, sources đi cùng chunk cuối, và trên /v1/messages thì đi cùng sự kiện message_delta. Các annotation đến trong một chunk ngay trước chunk cuối, dưới dạng delta.annotations.
• sources chỉ có khi lượt tìm kiếm của yêu cầu này tìm thấy kết quả. Phản hồi không có trường này được viết mà không có kết quả tìm kiếm.

Cách đếm lượt tìm kiếm

Mỗi gói bao gồm một số lượt tìm kiếm mỗi ngày:

• Yêu cầu có tìm kiếm ra kết quả dùng một lượt tìm kiếm trong hạn mức của ngày. Lượt tìm kiếm không ra kết quả thì không dùng lượt nào.
• Chat và API dùng chung hạn mức của tài khoản sở hữu key.
• Số đếm bắt đầu lại mỗi ngày lúc 00:00 UTC.
• Kết quả tìm kiếm là token đầu vào của yêu cầu và được tính phí cùng phần còn lại của prompt.

So sánh các gói

Khi lượt tìm kiếm của ngày đã hết

Yêu cầu gửi web_search: true sau lượt tìm kiếm cuối cùng của ngày không bị từ chối. Nó được trả lời mà không tìm kiếm: trạng thái là 200 và phản hồi không có sources.

Tìm kiếm như một tool của riêng bạn

web_search: true là công tắc duy nhất của tính năng tìm kiếm được mô tả ở đây. Một hàm bạn định nghĩa trong tools và đặt tên web_search là một tool của riêng bạn: model trả về một lần gọi, và mã của bạn chạy tìm kiếm rồi gửi kết quả trở lại.

Các loại tool tìm kiếm của nền tảng khác, như web_search_20250305 trên /v1/messages hoặc {"type": "web_search"} trên /v1/responses, không bắt đầu tìm kiếm ở đây.

Lỗi

Tìm kiếm web không thêm mã trạng thái hay loại lỗi nào. Lượt tìm kiếm không ra kết quả, hoặc ngày đã hết lượt tìm kiếm, cho một câu trả lời bình thường không có kết quả tìm kiếm. Mọi lỗi khác giống như với yêu cầu không có tìm kiếm. Xử lý lỗi