EnGenius Product SpecHub — RAG Search API
給其他部門 / 應用串接的對外文件 · 版本 v1 · 最後更新 2026-06-09
這支 API 讓你的應用查詢 EnGenius Product SpecHub 的知識庫(產品規格、技術文件、Help Center、WiFi 法規、官網頁面…),取得最相關的內容片段,再餵進你自己的 LLM / Agent 生成回答。我們負責「找到對的知識」,生成交給你 —— 標準的 RAG 檢索層。
1這是什麼
一個檢索(retrieval)端點:你送一段查詢,拿回知識庫裡最相關的幾段內容(含來源、相關度分數)。不回傳生成好的答案,生成由你端的模型負責 —— 這樣你完全掌控 prompt、模型與回答風格。
2Base URL
BASE https://engenie-eg.vercel.app
3認證
每個部門 / 應用會由 SpecHub 管理員核發一把 API key(sk_live_…)。每個請求帶:
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
安全規則: key 只在後端使用,絕不可放進前端 / 瀏覽器 / App 客戶端 / Git。純前端應用請由你自己的後端代理。key 可被管理員即時停用 / 輪替;懷疑外洩請立即通知換發。
4端點:POST /api/v1/search
POST /api/v1/search
Request Headers
| Header | 值 |
|---|---|
Authorization | Bearer <你的 key>(必填) |
Content-Type | application/json |
Request Body
| 欄位 | 型別 | 必填 | 說明 |
|---|---|---|---|
query | string | ✅ | 使用者的問題 / 查詢。支援中英日(跨語言)。最長 2000 字。 |
top_k | number | ✕ | 回傳幾筆。1–20,預設 8。 |
source_types | string[] | ✕ | 只查這些來源類型。只能在 key 允許範圍內縮小。 |
taxonomy | object | ✕ | 限定 Solution / 產品線 / 型號。一樣只能縮小。 |
source_types 可用值
| 值 | 內容 |
|---|---|
product_spec | 產品規格、overview、features |
gitbook | GitBook 技術文件 |
helpcenter | Help Center 文章(最佳實踐、功能說明) |
google_doc | Google Docs(訊息指南、產品簡報) |
wifi_regulation | 各國 WiFi 法規 |
web | 已索引的網頁 |
taxonomy 物件
{
"solution": "cloud", // solution slug;省略 = 不限
"product_lines": ["Cloud AP"], // 產品線名稱;省略 = 整個 solution
"models": ["ECW536"] // 型號;省略 = 不限型號
}
5回傳格式(200)
{
"ok": true,
"query": "Which access points support WiFi 7?",
"count": 3,
"scope": {
"client": "Sales Portal",
"taxonomy": { "solution": null, "product_lines": [], "models": [] },
"source_types": null
},
"results": [
{
"content": "ECW536 — Cloud7 4x4 … (相關片段內文)",
"title": "ECW536 — Cloud7 4x4",
"source_type": "product_spec",
"source_id": "ECW536",
"source_url": null,
"score": 0.6421,
"taxonomy": { "solution": "cloud", "product_lines": ["Cloud AP"], "models": ["ECW536"] }
}
]
}
| results[] 欄位 | 說明 |
|---|---|
content | 片段內文(已清洗,可直接餵 LLM) |
title | 該片段標題 |
source_type | 來源類型 |
source_id | 來源識別碼(型號、文章 slug、網址路徑…) |
source_url | 原始連結(若有;product_spec 為 null) |
score | 相關度分數(越高越相關) |
taxonomy | 該片段所屬 Solution / 產品線 / 型號 |
scope 會回傳這次實際生效的範圍(你的 key 範圍 ∩ 你的請求),方便除錯。
6Scope(範圍限制)
你的 key 由管理員綁定一個範圍上限:Solution / 產品線 / 型號 / 來源類型。
- 你可用
source_types/taxonomy再縮小,但永遠無法超出 key 的範圍。 - 若請求落在 key 允許之外,系統自動忽略該條件、退回 key 範圍(不會回傳越權內容)。
- 想擴大範圍,請聯絡管理員調整你的 key。
7速率限制
每把 key 有「每分鐘請求數」上限(預設 60/min)。超過回 429,稍候(固定 60 秒視窗)再試。請在使用者送出查詢時才呼叫,並可在你端做快取。
8錯誤碼
所有錯誤都回 JSON:{ "ok": false, "error": "…" }。
| HTTP | error 範例 | 原因 / 處理 |
|---|---|---|
400 | Missing 'query' / 'query' too long / Invalid JSON body | 請求格式錯誤,修正 body |
401 | Missing Authorization header / Invalid API key | 沒帶 key 或 key 錯誤 |
403 | API key disabled | key 已停用,聯絡管理員 |
429 | Rate limit exceeded | 超過速率上限,稍候重試 |
500 | Search failed. Try again shortly; if it persists, contact EnGenius. | 伺服器端錯誤,可重試;持續發生請回報(細節只在伺服器 log) |
9範例
cURL
curl -X POST https://engenie-eg.vercel.app/api/v1/search \
-H "Authorization: Bearer sk_live_xxx" \
-H "Content-Type: application/json" \
-d '{
"query": "哪些 AP 支援 WiFi 7?",
"top_k": 8,
"source_types": ["product_spec", "helpcenter"]
}'
JavaScript / Node(後端)
const res = await fetch("https://engenie-eg.vercel.app/api/v1/search", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.SPECHUB_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ query: "ECW536 和 ECW526 差在哪?", top_k: 6 }),
});
const data = await res.json();
if (!data.ok) throw new Error(data.error);
const context = data.results.map((r) => r.content).join("\n\n---\n\n");
Python(後端)
import os, requests
resp = requests.post(
"https://engenie-eg.vercel.app/api/v1/search",
headers={"Authorization": f"Bearer {os.environ['SPECHUB_API_KEY']}"},
json={"query": "推薦適合飯店的網路方案", "top_k": 8},
timeout=30,
)
data = resp.json()
if not data["ok"]:
raise RuntimeError(data["error"])
context = "\n\n---\n\n".join(r["content"] for r in data["results"])
10把結果串進你的 LLM(RAG 模式)
把 results[].content 串成 context,連同問題餵給你的模型:
你是 EnGenius 產品助理。只根據以下「參考資料」回答,不要編造。
若資料不足就說不知道。回答用使用者提問的語言。
參考資料:
{context} ← 把 results[].content 串起來放這
問題:{使用者的問題}
建議用 source_url / title 在回答裡標來源;score 偏低(例如 < 0.3)的片段可考慮捨棄。
11最佳實務與注意事項
- Server-to-server only:不開放 CORS,請從後端呼叫,key 不落地到瀏覽器。
- 語言:
query可用中 / 英 / 日,系統已對跨語言檢索做補強。 - query 精簡:只放當前要檢索的問題,不要把整段對話塞進去(超過 2000 字會被截)。
- 版本化:路徑帶
/v1;未來不相容變更會出/v2並保留過渡期。 - 內容更新:知識庫每天 / 每週自動更新,你查到的永遠是最新索引。