跳轉至

Synto

Synto（原名 OLW，全寫為 Open Language Wiki Pipeline）是 LLM Wiki 體系中負責將原始內容轉化為維基條目的自動化管道。它承接 raw input（例如網頁摘錄、技術筆記、會議紀錄），經 LLM 抽取、歸納、校對後，同步至 wiki 儲存庫，達致「raw → wiki」的單向流轉。

概述

Synto 的出現源於 LLM Wiki 的基本矛盾：LLM 輸出差異大，若直接寫入 wiki，容易產生格式失控、事實錯漏和碎片化。Synto 以可控的 pipeline 解決此問題，為每個條目建立可追溯的原始來源、轉換記錄和最終 Markdown 輸出。它的前身 OLW 只是內部實驗腳本，後來因應多個 Wiki 實例共用而重寫並改名為 Synto，象徵「合成」（synthesis）與「維基」（wiki）的結合。

在 benhoweb 的 Wiki 基建中，Synto 是檔期式（stage-based）處理器：每一條 raw 內容都會經歷「吸收 → 分析 → 生成 → 入庫」四個階段。它不直接面向讀者，而是面向編輯者與自動化流程，故此設計強調可預測性及冪等性（idempotency）。

架構

Synto 為容器化單體（modular monolith），內部可拆分為五個主要模組：

  1. Ingest Gateway：接收 raw 內容，支援 Markdown、純文字、JSON 及網頁抓取。所有輸入會先寫入本地佇列，避免後續處理阻塞。
  2. LLM Orchestrator：負責呼叫 LLM Provider。此層具備模型 fallback、重試、token 預算管理。Synto 本身不直接綁定單一模型供應商，而是透過 litellm 處理多供應商路由。
  3. Schema Mapper：將 LLM 回傳的結構化 JSON 轉換成 Wiki Markdown。內建多種條目模板，包括「服務條目」、「專案筆記」、「故障報告」。
  4. Sync Agent：比較新生成的 Markdown 與目標 wiki 的最新版本，只提交有實際差異的變更。
  5. State Store：以 SQLite 保存每筆 raw 的處理狀態、LLM 用量與輸出雜湊，用於稽核與重播。

在實際部署上，Synto 作為獨立容器放置於 Docker host 上，與 Wiki 儲存庫容器同屬一個 bridge 網絡。Synto 不直接暴露公開連接埠；所有對外通訊皆經 cloudflare-tunnel 轉發，故容器網絡僅採用內部網段，並以 cf_network 設定標記流量來源。

部署

Synto 以 Docker Compose 為主要部署方式。在 benhoweb 的環境中，Compose 檔指定兩項服務：synto-app 與 synto-db。

  • synto-app：使用自建鏡像 registry.benhoweb.com/library/synto:latest，設定 restart: unless-stopped，掛載 /srv/wiki/content 為 Wiki 內容儲存區。
  • synto-db：沿用 postgres:16-alpine，用作狀態儲存；具獨立 volume synto_db_data。

對外服務（例如管理儀表板）透過 Cloudflare Tunnel 而非直接 publish port。主機上僅監聽 127.0.0.1:8080 供本機管理工具存取。

部署流程如下：

  1. 拉取鏡像並更新 .env 中的 SYNTO_MODEL、SYNTO_WIKI_PATH。
  2. 執行 docker compose up -d。
  3. 以 docker compose exec synto-app synto check 驗證 pipeline 連線。
  4. 配置 crontab 或 systemd timer 呼叫 synto process --all。

配置

所有配置透過環境變數集中管理，主要參數包括：

  • SYNTO_WIKI_PATH：目標 wiki 的 Markdown 根目錄。
  • SYNTO_LLM_MODEL：預設模型名稱，例如 gpt-4o 或 claude-sonnet-4。
  • SYNTO_LLM_PROXY：指向 LiteLLM proxy 的 base URL。
  • SYNTO_LANGUAGE：輸出語言，設為 zh-HK 時會啟用香港用語替換表，例如「software」轉為「軟件」。
  • SYNTO_AUTO_COMMIT：設為 true 時，Synto 會直接將變更提交至 Git repo。
  • SYNTO_REQUIRE_REVIEW：若為 true，新條目會寫入 draft/ 目錄，等待人手審批後才移入正式路徑。

亦支援 YAML 設定檔（/etc/synto/config.yml）覆蓋環境變數，適合管理多個 Wiki 專案。建議只在 pipeline 管理人需要將不同 raw 來源分配到不同條目範本時使用。

維運與監控

Synto 的維運重點在於「確保處理過程可回播、輸出可追溯」。日常監控使用以下方式：

  • synto status：檢視佇列深度及最新錯誤。
  • docker compose logs -f：檢視 LLM API 回傳的錯誤碼，常見為 rate limit 或 context length。
  • 內建 Prometheus metrics endpoint：暴露於 /metrics，追蹤處理條目數、花費預算、failures 計數。

定期維護包括：

  • Volume 備份：synto_db_data 需每日備份；wiki 內容由 Git repo 管理，通常毋需另行備份。
  • Token 用量審計：每月從 LiteLLM 匯出用量報表，評估模型成本。
  • 佇列清理：刪除超過三十日的 failed raw record，釋放資料庫空間。
  • 鏡像更新：對於 latest tag，先於 staging 環境執行 synto process --dry-run，確認輸出 Markdown 通過 lint 才正式升級生產。

若 Cloudflare Tunnel 中斷，Synto 本身不影響運作（因為它主動向外連接），但管理儀表板會暫時無法存取，需檢查 cloudflared 容器狀態。

常見問題

1. 為何處理過的條目沒有出現在 wiki？
最常見原因是 SYNTO_REQUIRE_REVIEW=true，條目被置於 draft/。執行 synto review 檢視待批條目，或確認 SYNTO_AUTO_COMMIT 是否已設定。

2. LLM 回傳格式偶爾不穩定。
Synto 內建 JSON Schema 驗證，格式不符時會自動重試兩次；仍未通過則寫入錯誤佇列。建議在 synto-app 容器內執行 synto replay --id <ID> 手動重新處理。

3. 開始前如何試跑？
很安全，synto process --input file.md --dry-run 只輸出最終 Markdown 而不寫入 wiki。此模式亦是 CI/CD 常用的驗證步驟。

4. 香港用語替換不夠準確。
可於 /etc/synto/zh_HK_terms.csv 自訂替換詞表，格式為「簡體, 香港用語」，例如「雲端, 雲端」。詞表會套用於所有輸出條目。

相關鏈接

來源

自動生成（2026-08-19 容器覆蓋率補完第二批）