AI‑OES 搜尋插件設計與使用說明

檔案路徑：/nas2/kuang/MyPrograms/OES/ai_oes.py
作者：kuang@l40
授權：AGPL‑3.0-or‑later (可自行修改成其他 BSD / MIT 等，請自行調整 SPDX 識別)

本文件對 ai_oes.py 補充 設計架構、依賴、配置和使用流程，方便你在searx（或自訂的搜尋平台）中嵌入 AI 摘要功能。
若你想把此插件放到 Docker 容器內，亦可參考下方的 部署指引。

1️⃣ 目錄

2️⃣ 依賴

::: note

如果是在 Docker 內部執行 searx, 請確認 requirements.txt 中包含 markdown-it-py 及 requests。
其它依賴直接由 searx 安裝。

:::

3️⃣ 專案目錄

/nas2/kuang/MyPrograms/searxng/
├─ searx/plugins/ai_oes.py            ← 本插件 (主入口)
├─ searx/settings.yml   ← searx 主設定檔 (須加載該插件)
├─ config/settings.yml   ← searx 外部設定檔 (Docker執行時會加載此檔)
└─ requirements.txt     ← 若使用 Docker 或 pip 安裝

searx/settings.yml 中加入

plugins:
 - ai_oes

• 若編譯 searx 的 Docker 版，則
  • 修改 searx/settings.yml 之後，重新建構容器，
  • 還要注意外部config/settings.yml需同步更新。

4️⃣ 設計概觀

插件整體流程：

1. 用戶輸入 ai <關鍵字> → pre_search 會偵測到前綴 ai
2. search_query.query 被截掉 ai，並在 search 物件上寫 _ai_mode = True
3. 搜尋器完成後，post_search 在 container 內執行 delayed_collect()
4. 收到搜尋結果（最多 30 筆摘要），組成 prompt → call_vllm
5. vLLM 回傳 Markdown → 轉成純文字 → 形成 Answer 回傳
6. 前端得到 AI 摘要，並在搜尋結果頁面顯示。

注意：為了減少等待時間， delayed_collect 只等待最大 3 秒（30 次 0.1 秒）。如果搜尋還沒完成，插件會先回傳「正在處理」的 placeholder；若 5 秒內仍無結果，則直接返回 placeholder 內文字。

5️⃣ 重要屬性與方法說明

class SXNGPlugin(Plugin):
    # --- 基本屬性 ---------------------------------------------------------------
    id         : str          # 唯一標識，必須與檔名相同
    name       : str          # 顯示名稱
    description: str          # 描述文字（可在 UI 內直接顯示）
    keywords   : List[str]    # 搜索關鍵字，預留組件

5.1 __init__(self, plg_cfg: PluginCfg)

• 初始化 api_url, api_key (若為 OpenAI service)
• 建立 self.info，供 searx 讀取插件資訊；也讓你在 searx.conf 的 preference_section 調整 UI。

5.2 pre_search(self, request, search)

• 功能：偵測前綴 ai → 清除之並設 _ai_mode
• 參數
  • request – searx 的 HTTP Request
  • search – search manager 对象（含 search_query、result_container 等）
• 返回：True 以讓搜尋繼續（必須）

5.3 post_search(self, request, search)

1. 判斷：若 _ai_mode 為 False → 直接回傳空列表
2. 建立佔位：Answer(answer="AI Output, ...")，告知前端「AI 正在產生」
3. 背景執行 delayed_collect()：
   • 等待搜尋結果容器 (container)關閉
   • 取 main_results_sorted 或 main_results_map
   • 若有結果，將前 30 筆作 prompt → call_vllm
   • 生成 Markdown 摘要後加入 container.answers。

5.4 call_vllm(text: str)

• HTTP POST 內容示例：

  payload = {
      "model": "openai/gpt-oss-20b",
      "messages": [{"role": "user", "content": text}],
      "temperature": 0.1,
      "max_tokens": 100000,
  }
  

• 可自行改成 gpt-4、gpt-4o-mini 或其他任何兼容 OpenAI 的 vLLM endpoint。

5.5 delayed_collect 內部實作

for i in range(30):  # 3s max wait
    if getattr(container, "closed", None) or getattr(container, "_closed", False):
        break
    time.sleep(0.1)

• 減少多執行緒之間競爭，確保搜尋結果已完全寫入。

6️⃣ 如何啟用

1. 放置檔案
   把 ai_oes.py 放在你自己的 searx 插件目錄下，或直接複製到
   /searx/searx/engine/plugins/ai_oes.py（如果是 local build）。

2. 修改 searx.conf
   ```yaml plugins:
   • ai_oes ``` 若 searx 已經存在 preference_section，請將 preference_section 加到 PluginInfo。
3. 重新啟動 searx

   # 若你使用 docker-compose
   docker-compose restart searx
   
   # 若你使用 local python
   python searx/bin/searx.py
   

4. 使用
   在搜尋欄直接輸入 ai 會計師合約" 隨便寫個關鍵字，提示 leading AI。

7️⃣ 配置項

如果你想覆寫預設值，可在 searx/settings.yml 的 [plugins] 區塊中, 或在 searx 內部自行載入 config。

示範：

plugins:
  - id: ai_oes
    api_url: http://172.20.31.7:8001/v1/chat/completions   # 你自己 vLLM endpoint
    api_key: <YOUR_OPENAI_KEY>  # 若使用外部 OpenAI，需要填寫 token
    response_timeout: 20   # 送往 vLLM 的超時秒數

說明

1. api_url：默認為本機 vLLM endpoint，亦可改成 https://api.openai.com/v1/chat/completions
2. api_key：若使用 OpenAI 正式 API，必填；若使用 vLLM 本地部署可以留空
3. response_timeout：5～30 秒之間均可，根據模型預測時間調整

若你想要修改生成摘要長度、溫度、prompt 範本，請直接調整以下片段：

prompt = (
    f"以下是查詢「{query_text}」的前 3 頁搜尋結果，"
    f"請用中文撰寫重點摘要與整合結論(不要列表)：\n\n"
    + "\n".join(text_block)
)

8️⃣ 使用範例

測試腳本（可放到 tests/ai_test.py）：

import requests, json, time

SEARCH_URL = "http://127.0.0.1:5000/search?search_query=ai%20環境法%20第十條"

resp = requests.get(SEARCH_URL)
print(json.dumps(resp.json(), indent=2, ensure_ascii=False))

你可以在這個腳本中驗證 Answer 是否出現在 results 之列表中。

9️⃣ 常見問題（FAQ）

1️⃣0️⃣ Docker / Kubernetes 部署

重新編譯

• 此處用到了requests模組，需要在Docker裡面也安裝這個模組

cd /nas2/kuang/MyPrograms/searxng
echo 'requests==2.32.5' >> requirements.txt
make clean
make container.build

Dockerfile 範例

# Docker for searx with ai_oes plugin
FROM searx/searx:latest

RUN pip install --no-cache-dir markdown-it-py requests

# Copy plugin & enable
COPY ai_oes.py /searx/searx/engine/plugins/ai_oes.py
COPY my_searx.conf /etc/searx/settings.yml

CMD ["searx", "--ip=0.0.0.0", "--port=5000", "--debug"]

Kubernetes Service

apiVersion: apps/v1
kind: Deployment
metadata:
  name: searx-ai
spec:
  replicas: 1
  selector:
    matchLabels:
      app: searx-ai
  template:
    metadata:
      labels:
        app: searx-ai
    spec:
      containers:
      - name: searx
        image: your-repo/searx-ai:latest
        env:
        - name: SEARX_DEBUG
          value: "true"
        - name: SEARX_API_URL
          value: "http://172.20.31.7:8001/v1/chat/completions"
        ports:
        - containerPort: 5000

將 SEARX_API_URL 或其他環境變數傳入 searx/settings.yml（可利用 jinja2 版 searx.conf 加載環境變數）

1️⃣1️⃣ 參考資料

🔧 拓展方式

小結

• AI‑OES plugin 為 searx 提供「人類可讀摘要」的功能，透過 vLLM 模型簡單實現。
• 只要在 searx/settings.yml 加載插件、設定 api_url，即可在搜尋框前加 ai 來啟動 AI 摘要。
• 它使用多執行緒等待搜尋結果，最大等待 3 秒，最後將 AI 摘要 Answer 儲存至 container.answers。
• 若需調整 prompt、token 或模型，只需改寫 call_vllm 或 post_search 內的文字。
• 若遇大數據、低延遲，請將 delayed_collect 改為同步或增大等待時間。

祝你玩得開心，順利把 AI 進一步整合進搜尋平台！ 🚀