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值
AuthorizationBearer <你的 key>(必填)
Content-Typeapplication/json

Request Body

欄位型別必填說明
querystring✅使用者的問題 / 查詢。支援中英日(跨語言)。最長 2000 字。
top_knumber✕回傳幾筆。1–20,預設 8。
source_typesstring[]✕只查這些來源類型。只能在 key 允許範圍內縮小。
taxonomyobject✕限定 Solution / 產品線 / 型號。一樣只能縮小。

source_types 可用值

值內容
product_spec產品規格、overview、features
gitbookGitBook 技術文件
helpcenterHelp Center 文章(最佳實踐、功能說明)
google_docGoogle 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 / 產品線 / 型號 / 來源類型。

7速率限制

每把 key 有「每分鐘請求數」上限(預設 60/min)。超過回 429,稍候(固定 60 秒視窗)再試。請在使用者送出查詢時才呼叫,並可在你端做快取。

8錯誤碼

所有錯誤都回 JSON:{ "ok": false, "error": "…" }。

HTTPerror 範例原因 / 處理
400Missing 'query' / 'query' too long / Invalid JSON body請求格式錯誤,修正 body
401Missing Authorization header / Invalid API key沒帶 key 或 key 錯誤
403API key disabledkey 已停用,聯絡管理員
429Rate limit exceeded超過速率上限,稍候重試
500Search 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最佳實務與注意事項