Web Search

Cho phép model tham khảo thông tin mới nhất từ internet khi trả lời — tin tức, giá cả, tỷ giá, sự kiện thời gian thực. Bật bằng cách thêm tool web_search vào request, không cần endpoint riêng.

Bật web search

Thêm tools: [{ "type": "web_search" }] vào request /v1/chat/completions bình thường:

{
  "model": "gemini-2.5-flash",
  "messages": [
    { "role": "user", "content": "Giá vàng SJC hôm nay bao nhiêu?" }
  ],
  "tools": [{ "type": "web_search" }],
  "stream": true
}

Beeknoee sẽ tự động: tìm trên internet → đưa kết quả vào ngữ cảnh → model đọc và trả lời kèm trích nguồn. Toàn bộ diễn ra trong một lần gọi API, response trả về đúng định dạng OpenAI như thường.

Ví dụ

curl https://platform.beeknoee.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash",
    "messages": [{ "role": "user", "content": "Tin tức AI mới nhất tuần này?" }],
    "tools": [{ "type": "web_search" }]
  }'

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://platform.beeknoee.com/v1",
)

resp = client.chat.completions.create(
    model="gemini-2.5-flash",
    messages=[{"role": "user", "content": "Tỷ giá USD/VND hôm nay?"}],
    tools=[{"type": "web_search"}],
)
print(resp.choices[0].message.content)

Tham số (tùy chọn)

Có thể truyền thêm trong tool object:

{ "type": "web_search", "query": "OpenAI GPT-5 release date", "max_results": 5 }

💡 Các cú pháp tương đương cũng được chấp nhận: web_search_preview (OpenAI Responses), web_search_20250305 (Anthropic), beeknoee:web_search.

⚠️ Nếu agent của bạn đã có tool tìm kiếm riêng tên web_search — tức là một khai báo hàm đầy đủ ({"type":"function","function":{"name":"web_search","parameters":{…}}} hoặc khuôn Anthropic có input_schema) — Beeknoee không đụng vào nó: model sẽ trả tool_call về để agent của bạn tự chạy, và bạn không bị tính phí web search. Muốn dùng web search của Beeknoee thì thêm {"type":"web_search"} như trên; hai thứ dùng song song được.

Chi phí

• Chỉ tính phí khi tìm thành công. Nếu tìm thất bại, hệ thống tự bỏ qua và model vẫn trả lời (không tính 200đ).
• Cache 10 phút: cùng một câu hỏi trong 10 phút dùng lại kết quả cũ (vẫn tính phí, nhưng nhanh hơn).
• Phụ phí web search độc lập với token cost và không bị giảm giá theo gói.

Model nào hỗ trợ?

Không phải model nào cũng bật được web search. Kiểm tra qua GET /v1/models — model hỗ trợ có cờ supports_web_search: true.

• Gọi web_search trên model không hỗ trợ → trả lỗi 400 unsupported_feature.
• Trong Playground, nút 🌐 Web Search chỉ hiện khi model đang chọn hỗ trợ.

Cơ chế hoạt động

Beeknoee dùng hai cách, tự động chọn theo model:

1. Tìm & chèn ngữ cảnh (mặc định): Beeknoee tìm qua công cụ tìm kiếm, làm sạch kết quả, chèn vào ngữ cảnh dưới dạng nguồn tham khảo, rồi gọi model. Áp dụng cho mọi model hỗ trợ.
2. Grounding gốc của Gemini (model Gemini đi thẳng tới Google): để Gemini tự tìm bằng Google Search tích hợp sẵn, cho kết quả và trích dẫn chuẩn hơn.

Dù dùng cách nào, response trả về cho bạn vẫn giống hệt nhau.

Lưu ý

• Kết quả tìm kiếm được coi là dữ liệu tham khảo, không phải chỉ thị — model được hướng dẫn không làm theo lệnh ẩn trong nội dung web (chống prompt injection).
• Web search thêm khoảng 0.5–2 giây độ trễ trước khi model bắt đầu trả lời.
• Nên dùng kèm "stream": true để có trải nghiệm mượt và tránh timeout với câu trả lời dài.

Endpoint tìm kiếm riêng — POST /v1/search

Ngoài cách gắn tool vào chat ở trên, bạn có thể gọi web search như một model riêng để lấy thẳng kết quả tìm kiếm (kèm câu trả lời tổng hợp), không cần model chat. Dùng khi bạn chỉ cần dữ liệu search thô để tự xử lý.

• Endpoint: POST https://platform.beeknoee.com/v1/search
• Model: web-search
• Giá: 200đ / request, chỉ tính khi có kết quả (rỗng/thất bại → 0đ).

Request

{ "model": "web-search", "query": "giá vàng SJC hôm nay", "max_results": 5 }

Response

{
  "object": "search.result",
  "model": "web-search",
  "query": "giá vàng SJC hôm nay",
  "cached": false,
  "answer": "Giá vàng SJC hôm nay khoảng 149,9 triệu đồng/lượng bán ra ...",
  "results": [
    { "index": 0, "title": "baomoi.com", "url": "https://...", "snippet": "", "domain": "..." }
  ],
  "usage": { "results": 5, "cost_vnd": 200 }
}

• answer = câu trả lời tổng hợp, có khi công cụ tìm kiếm phục vụ request đó hỗ trợ grounding; null với công cụ chỉ trả snippet.
• Với grounding, snippet thường rỗng và url là link trích dẫn (redirect) — dùng answer làm nội dung chính.
• Không có kết quả: nếu tất cả nguồn tìm kiếm lỗi/hết quota → trả HTTP 503 {"error":{"message":"Web search tạm thời không khả dụng..."}} và không tính phí.

cURL

curl https://platform.beeknoee.com/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "web-search", "query": "Tin tức AI mới nhất", "max_results": 5 }'

Nên dùng cái nào?

Xem thêm

• Chat Completions — tham số đầy đủ của endpoint
• API Usage — theo dõi chi phí (web search hiển thị trong lịch sử dùng)
• Error Handling — mã lỗi & retry