這篇教學的每一條指令都來自本站在 RTX A6000 48 GB 工作站 上實際錄下的終端機過程（2026-11-03 的版本，commit dddbbdbc7991），照順序做即可。
開始前
本次測試環境為 Ubuntu 24.04 LTS（Linux kernel 7.0.0-38-generic），搭配 Intel Core i7-9700 CPU 與 62 GB RAM。顯卡為兩張 NVIDIA RTX A6000（驅動版本 580.159.03），雖然 xerj 核心為 Rust 編譯的二進位檔，但建議具備 GPU 以加速向量嵌入處理。軟體方面需安裝 Python 3.12.3、uv 0.11.2 以及 Node.js v18.19.1。
安裝與執行
步驟 1：取得原始碼
從 GitHub 下載 xerj 專案的特定 commit（dddbbdb），以便後續參考或除錯。
git clone https://github.com/xerj-org/xerj xerj cd xerj
成功時會看到：git log 顯示 commit 'dddbbdb 2026-11-02'，目錄大小約 297M，包含 engine、server 等資料夾。（這一步我們花了 1.8 秒，結束碼 0）
content funding.json README.fa.md tools CONTRIBUTING.md glama.json README.ja-JP.md user-feedback demo landing README.ko.md wrangler.toml demo_project LICENSE README.md xerj-ux deploy metrics README.zh-CN.md docs metrics-worker recipes
步驟 2：安裝執行檔
使用官方安裝腳本下載並安裝 xerj v1.0.0-rc.100 的 Linux 二進位檔。
curl -fsSL https://xerj.org/get | sh
成功時會看到：終端機顯示 'ok sha256 verified' 與 'ok installed /home/user/.local/bin/xerj'，最後提示 'xerj v1.0.0-rc.100 is ready'。（這一步我們花了 31.6 秒，結束碼 0）
==> extracting… ok installed /home/user/.local/bin/xerj xerj v1.0.0-rc.100 is ready. start it: xerj --insecure --data-dir ~/xerj-data then open the console: http://localhost:9200/_xerj-console/ docs: https://xerj.org/docs/ · source: https://github.com/xerj-org/xerj
步驟 3：建立測試專案
創建一個包含 Python 程式碼與 Markdown 文件的簡單目錄，作為後續索引與搜尋的對象。
export PATH="$HOME/.local/bin:$PATH" && mkdir -p demo_project && printf 'def hello():\n return "world"\n' > demo_project/main.py && printf '# Demo\n\nhello world example project\n' > demo_project/README.md
成功時會看到：指令執行無錯誤輸出，成功建立 demo_project 目錄及 main.py、README.md 檔案。（這一步我們花了 0.0 秒，結束碼 0）
步驟 4：啟動服務
在背景啟動 xerj 服務，開啟 REST API、Elasticsearch 相容介面與 gRPC 端口。
before=$(ss -Hltn 2>/dev/null | awk '{print $4}' | sort); setsid nohup bash -c 'xerj --insecure --data-dir ./xerj-data' > "$RUN/bg-$(date +%s).log" 2>&1 < /dev/null & echo "背景啟動：xerj --insecure --data-dir ./xerj-data"; for i in $(seq 1 30); do sleep 1; after=$(ss -Hltn 2>/dev/null | awk '{print $4}' | sort); [ "$after" != "$before" ] && break; done; comm -13 <(echo "$before") <(echo "$after") | sed 's/^/ 新開的埠 /'; tail -n 5 "$RUN"/bg-*.log 2>/dev/null成功時會看到：日誌顯示 'native REST listening on 127.0.0.1:8080'、'ES-compat listening on 127.0.0.1:9200' 與 'gRPC ... listening on 127.0.0.1:8081'。（這一步我們花了 1.1 秒，結束碼 0）
新開的埠 127.0.0.1:8081 新開的埠 127.0.0.1:9200 2026-11-03T04:57:22.796916Z INFO xerj: native REST listening on 127.0.0.1:8080 2026-11-03T04:57:22.796860Z INFO xerj_engine::engine: memory/disk sampler thread started (parent circuit breaker) period_ms=100 2026-11-03T04:57:22.796973Z INFO xerj: ES-compat listening on 127.0.0.1:9200 2026-11-03T04:57:22.797099Z INFO xerj::grpc: gRPC XerjSearch + XerjHub listening on 127.0.0.1:8081
步驟 5：等待服務就緒
輪詢檢查 Elasticsearch 相容端點，確保服務已完全啟動並可接受請求。
for i in $(seq 1 30); do curl -sf http://localhost:9200/ >/dev/null && break; sleep 1; done; curl -s http://localhost:9200/ | head -c 400; echo
成功時會看到：curl 回應 JSON 資料，包含 'cluster_name':'xerj' 與 'tagline':'You Know, for Search'。（這一步我們花了 0.0 秒，結束碼 0）
$ for i in $(seq 1 30); do curl -sf http://localhost:9200/ >/dev/null && break; sleep 1; done; curl -s http://localhost:9200/ | head -c 400; echo
步驟 6：索引測試資料
使用 autoindex 指令對 demo_project 進行全文與向量索引，建立搜尋基礎。
xerj autoindex ./demo_project
成功時會看到：進度條跑完後顯示 'ok: indexed and searchable'，並回報 'done in 1.3s — 1 dataset, 3 records live'。（這一步我們花了 1.7 秒，結束碼 0）
(add the same --url and --api-key the map line above used)
this corpus mixes code and prose — code volume can swamp prose on
shared words. Scope one side with a filter on `ax_format`
(values in this run: code, txt-prose).
Prose sections are stored in `body`; line files such as changelogs
are stored in `text`, so a match on `body` alone misses them.步驟 7：執行全文搜尋
透過 xerj search 指令驗證索引是否生效，搜尋關鍵字 'hello world'。
xerj search 'hello world'
成功時會看到：輸出列出 README.md 與 main.py 的匹配片段，並顯示相關性分數（score 1.74 與 0.38）。（這一步我們花了 0.1 秒，結束碼 0）
# Demo
hello world example project
─── main.py:1 (score 0.38)
def hello():
return "world"
2 passage(s) from 'ax-*'. Cite ax_path:line (ax_path#locator for a data row) for anything you rely on.步驟 8：關閉服務
測試結束後，終止背景執行的 xerj 程序以釋放資源。
pkill -f 'xerj --insecure' || true
成功時會看到：pkill 指令執行成功，無錯誤訊息。（這一步我們花了 0.1 秒，結束碼 0）
$ pkill -f 'xerj --insecure' || true
確認裝好了
執行 xerj search 'hello world' 後，若終端機回傳包含 README.md 與 main.py 的搜尋結果，且顯示 '2 passage(s) from 'ax-*''，代表索引與搜尋功能均正常運作。
可能遇到的問題
1. 若 git clone 時出現 'WARNING: terminal is not fully functional'，請按 Enter 鍵繼續即可，不影響後續步驟。
接下來
安裝完成後，您可以嘗試將 xerj 整合至 AI 代理的工作流中，利用其 Elasticsearch 相容 API 或 gRPC 介面進行更複雜的混合搜尋（Hybrid Search），或參考官方文件設定 MCP Server 以連接大型語言模型。
- 它是什麼、解決什麼問題：XERJ 是什麼：專為 AI 代理設計的本地化 Rust 搜尋引擎
- 本站的實測結果：xerj 實測：單執行檔本地搜尋引擎，1.7 秒索引並回傳引用來源
