# Local Search

> 本地文档检索与 RAG 工具，支持多 Workspace 管理。 当用户需要： (1) 在本地文档库中搜索信息 (2) 管理多个文档集合（workspace） (3) 将本地文件/目录（支持 md, pdf, txt, srt, ass）入库并向量化 使用此 skill。

- Skill: `id-verne/local-search` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add id-verne/local-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/id-verne/local-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: id-verne (https://skillmd.com/u/id-verne)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/id-verne/local-search

---


# Local Search - 本地 RAG 检索工具

这是一个轻量级、可移植的本地 RAG 检索库。

## ⚠️ 首次使用 / 环境初始化 (CRITICAL)

由于包含 C++ 扩展（hnswlib），本 Skill **不包含** 预编译环境。
**在任何项目中使用此 Skill 时，Agent 必须首先执行以下命令来初始化环境：**

```powershell
# 使用 run_shell_command 执行
.\scripts\install.ps1
```

该脚本将自动：
1. 检查或创建 `.venv` 虚拟环境。
2. 安装所有必需的依赖项（numpy, hnswlib, openai, pdfplumber, requests 等）。
**切勿将 `.venv` 提交到版本控制系统中。**

---

## 使用方式

环境初始化成功后，你可以通过 CLI 脚本快速执行入库和检索任务。
默认情况下，索引数据会保存在当前命令执行目录下的 `local_search_data` 文件夹中。

### 1. 检查当前状态
```powershell
.\.venv\Scripts\python.exe .\scripts\run_local_search.py --status
```

### 2. 文档入库 (Ingest)
自动扫描目标文件夹并将支持的文件入库。
```powershell
# 将 "docs" 文件夹内容入库到 "my_project" 工作区
.\.venv\Scripts\python.exe .\scripts\run_local_search.py --workspace "my_project" --ingest "./docs"
```

### 3. 检索 (Search)
在指定工作区中进行混合检索（基于向量和 SiliconFlow Rerank）。
```powershell
.\.venv\Scripts\python.exe .\scripts\run_local_search.py --workspace "my_project" --query "如何使用 RAG？" --top-k 5
```

---

## 进阶：通过 Python 脚本调用 API

如果 CLI 无法满足复杂的逻辑流，你可以写一个临时的 Python 脚本并在 `.venv` 中运行它：

```python
# test_rag.py
import sys
from pathlib import Path

# 确保能找到 local_search 模块
sys.path.append(str(Path(".").resolve() / "scripts"))

from local_search import create_local_search_tool

tool = create_local_search_tool(
    reranker_api_key="your-siliconflow-api-key",  # 不传将使用默认测试 key
    use_silicon_flow=True,
)

# 入库
tool.add_directory("./我的文档", recursive=True)

# 搜索
results = tool.search("目标关键词", top_k=3)
print(tool.format_results(results))
```
执行：`.\.venv\Scripts\python.exe test_rag.py`

## 路径与工作区说明
- `local_search_data`：默认的数据存储目录，相对于启动 Agent 时所在的当前工作目录创建。
- **Workspace**：代表一个独立的向量库。可以通过 `--workspace <名称>` 隔离不同项目或知识领域的文档。如果不指定，则默认放入 `default` 工作区。