semantic-search（语义搜索）

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)

搜索文本文件或表格文件

输入:

{
  "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*