name: semantic-search description: 企業級語義檢索技能，支援表格/欄位/檔案搜尋和 Text-to-SQL 資料生成 author: 小白 (基於 semantic_search 專案定製) metadata: openclaw: emoji: 🔍 requires: bins: [python3] env: - FLIGHT_DB_HOST - FLIGHT_DB_PORT - FLIGHT_DB_USER - FLIGHT_DB_PASSWORD

Semantic Search - 企業級語義檢索技能

基於 semantic_search 專案定製的企業級語義檢索技能，支援表格檢索、欄位檢索、檔案檢索和 Text-to-SQL 資料生成。

核心功能

1. 表格語義檢索 (table_search)

根據自然語言查詢檢索相關的資料庫表

輸入:

{
  "query": "查詢包含使用者資訊的表",
  "resource_ids": [1, 2, 3],
  "limit": 10,
  "enable_query_enhancement": true,
  "enable_rewrite": false,
  "enable_hyde": false,
  "enable_keywords": true
}

輸出:

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "resource_id": 1,
      "resource_name": "使用者資料庫",
      "view_name": "user_info"
    }
  ]
}

2. 欄位語義檢索 (field_search)

根據自然語言和表資訊檢索相關欄位

輸入:

{
  "query": "查詢使用者的建立時間欄位",
  "resource_id": 1,
  "limit": 5
}

輸出:

{
  "code": 200,
  "msg": "success",
  "data": ["created_at", "create_time", "user_created"]
}

3. Text-to-SQL 資料生成 (data_gen)

根據自然語言生成 SQL 並提取資料

輸入:

{
  "query": "查詢最近註冊的使用者數量",
  "resource_id": 1,
  "return_all": false,
  "max_attempts": 2,
  "confidence_threshold": 0.8
}

輸出:

{
  "code": 200,
  "msg": "success",
  "data": {
    "result": {"count": 1234},
    "sql": "SELECT COUNT(*) FROM user_info WHERE created_at >= NOW() - INTERVAL '7 days'"
  }
}

4. 檔案語義檢索 (file_search)

搜尋文本檔案或表格檔案

7w4.net小蔥技能。

輸入:

{
  "query": "查詢使用者手冊文件",
  "search_type": "text",
  "limit": 10
}

輸出:

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "resource_id": 5,
      "resource_name": "使用者手冊.pdf"
    }
  ]
}

技術架構

核心元件

semantic-search/
├── SKILL.md                 # 本檔案
├── README.md                # 使用說明
├── _meta.json               # 後設資料
└── src/
    ├── __init__.py
    ├── semantic_search.py   # 核心檢索類
    ├── retriever.py         # 檢索器
    ├── text2sql.py          # Text-to-SQL
    └── graph/
        ├── base.py          # 基礎圖編排
        ├── structured.py    # 結構化檢索圖
        ├── field.py         # 欄位檢索圖
        └── unstructured.py  # 非結構化檢索圖

技術棧

檢索流程

使用者查詢
    ↓
意圖識別 (LLM)
    ↓
路由分發
    ├→ 欄位檢索 → FieldGraph → 返回欄位列表
    ├→ 內容檢索
    │   ├→ 單 ID 查詢 → 直接獲取
    │   ├→ 多 ID 查詢 → 排序後返回
    │   ├→ 結構化檢索 → StructuredGraph (表格)
    │   └→ 非結構化檢索 → UnstructuredGraph (檔案)
    ↓
結果合併 → Rerank → 返回

安裝步驟

1. 安裝依賴

cd skills/semantic-search
pip install -r requirements.txt

2. 配置環境變數

export FLIGHT_DB_HOST="localhost"
export FLIGHT_DB_PORT="31337"
export FLIGHT_DB_USER="admin"
export FLIGHT_DB_PASSWORD="your_password"

或通過配置檔案 config.yaml:

flight_db:
  host: localhost
  port: 31337
  user: admin
  password: your_password
  insecure: true

3. 測試技能

python -m src.test_search

使用方法

在 OpenClaw 中呼叫

# 表格檢索
result = await skill.invoke("semantic-search", {
    "action": "table_search",
    "query": "查詢使用者相關的表",
    "limit": 10
})

# 欄位檢索
result = await skill.invoke("semantic-search", {
    "action": "field_search",
    "query": "查詢建立時間欄位",
    "resource_id": 1,
    "limit": 5
})

# Text-to-SQL
result = await skill.invoke("semantic-search", {
    "action": "data_gen",
    "query": "查詢最近註冊使用者數",
    "resource_id": 1
})

# 檔案檢索
result = await skill.invoke("semantic-search", {
    "action": "file_search",
    "query": "查詢使用者手冊",
    "search_type": "text",
    "limit": 10
})

直接使用 Python

from src.semantic import SemanticSearch, DataGen

# 表格檢索
search = SemanticSearch()
tables = await search.query2table(
    query="查詢使用者相關的表",
    _filter=[1, 2, 3],
    limit=10
)

# 欄位檢索
fields = await search.query2field(
    query="查詢建立時間欄位",
    resource_id=1,
    limit=5
)

# Text-to-SQL
data_gen = DataGen()
result, sql = await data_gen.query2sql(
    query="查詢最近註冊使用者數",
    resource_id=1,
    max_attempts=2,
    confidence_threshold=0.8
)

高階配置

查詢增強

啟用查詢增強可以提升檢索精度：

{
  "enable_query_enhancement": true,
  "enable_rewrite": true,
  "enable_hyde": true,
  "enable_keywords": true
}

• enable_query_enhancement: 使用 LLM 增強查詢
• enable_rewrite: 查詢改寫
• enable_hyde: HyDE 生成（Hypothetical Document Embeddings）
• enable_keywords: 關鍵詞提取

效能最佳化

批次檢索:

# 批次查詢多個資源
results = await search.batch_query(
    queries=["查詢 1", "查詢 2"],
    resource_ids=[[1, 2], [3, 4]],
    parallel=True
)

快取配置:

# 啟用快取
search = SemanticSearch(cache_ttl=300)  # 5 分鐘快取

故障排查

常見問題

1. 連線失敗

Error: Connection refused to FlightSQL server

解決：檢查 FLIGHT_DB_HOST 和 FLIGHT_DB_PORT 配置

2. 向量化失敗

Error: Embedding API timeout

解決：檢查 Embedding 服務狀態，增加 timeout

3. 無結果返回

Warning: No results found for query

解決： - 檢查資源 ID 是否正確 - 嘗試增加 limit 引數 - 檢查向量索引是否已構建

日誌除錯

啟用詳細日誌：

export LOG_LEVEL=DEBUG
python -m src.semantic_search

效能指標

更新日誌

v1.0.0 (2026-03-04)

• ✅ 初始版本釋出
• ✅ 表格檢索功能
• ✅ 欄位檢索功能
• ✅ Text-to-SQL 資料生成
• ✅ 檔案檢索功能
• ✅ LanceDB/FlightSQL 整合
• ✅ LangGraph 工作流編排

許可證

MIT License

聯絡方式

• 專案地址: https://github.com/semantic-search
• 問題反饋: https://github.com/semantic-search/issues

基於 semantic_search 專案定製 | 建立時間：2026-03-04

這個 Skill 整體質量中等偏下，核心檢索功能設計完善，但存在致命缺陷：由於引用了大量未打包的專案模組，單獨安裝後無法正常執行，依賴外部專案環境。文件說明較詳細，但實際使用時會遇到配置缺失的問題。優點是功能覆蓋全面、文件完善。如需使用，必須在完整的專案環境中部署，否則會出現找不到模組的錯誤。