local-ai-search
Natural language search for local files (100G-1T). Supports xlsx, pptx, pdf, docx formats with location info. Triggered when user asks to search local/computer/folder content.
安装 / 下载方式
TotalClaw CLI推荐
totalclaw install github:LeoYeAI~openclaw-master-skills~local-ai-searchcURL直接下载，无需登录
curl -fsSL https://skills.taituai.com/api/skills/github%3ALeoYeAI~openclaw-master-skills~local-ai-search/file -o local-ai-search.md# Local AI Search
## 触发条件
**当用户说以下内容时，调用此 Skill：**
- "帮我在本地搜索..."
- "帮我在本电脑搜索..."
- "帮我在某个文件夹中搜索..."
- "搜索本地文件..."
- "搜索我的文档..."
- "在本机查找..."
- "从我的文件中查找..."
- 或任何涉及**本地/本机/文件夹内容检索**的请求
## 功能说明
本 Skill 提供本地文件的 AI 智能搜索功能：
- ✅ 支持 xlsx, pptx, pdf, docx, md 等格式
- ✅ 自然语言查询（用日常语言描述要找的内容）
- ✅ 指定文件夹范围进行搜索
- ✅ 返回文件位置信息（工作表名、幻灯片页码）
- ✅ 无需本地大模型，使用云端 API
## 使用方式
### 方式一：直接搜索（推荐）
```
用户: 帮我在本地搜索关于销售数据的内容
用户: 在 ~/Documents/Projects 文件夹中搜索 API 相关的文档
用户: 搜索本电脑中包含"关键词"的文件
```
### 方式二：指定目录搜索
```
用户: 帮我在 ~/Documents/Projects 文件夹中搜索技术文档
```
### 方式三：自然语言查询
```
用户: 帮我找一下第三季度的销售报告
用户: 搜索一下关于数字化转型的内容
用户: 找找看有没有关于项目计划的 PPT
```
## 调用流程
1. **检查服务状态**：确认 Khoj 服务是否运行
2. **确定搜索范围**：用户指定的文件夹，或默认已索引的知识库
3. **执行搜索**：使用自然语言查询本地文件
4. **返回结果**：显示匹配的文件名、位置信息、内容片段
---
## 快速验证（已测试）
```bash
# 1. 启动 Khoj 服务（嵌入式 PostgreSQL 模式）
export USE_EMBEDDED_DB="true"
khoj --anonymous-mode
# 2. 转换文档
~/.agents/skills/local-ai-search/scripts/convert.py ~/Documents/source -o ~/Documents/converted
# 3. 索引文件（API 方式）
curl -X PATCH "http://localhost:42110/api/content" \
-F "files=@~/Documents/converted/example.xlsx.md"
# 4. 搜索查询
~/.agents/skills/local-ai-search/scripts/query.py "搜索内容"
```
### 验证结果示例
```
[1] 文件: test_data.xlsx.md
工作表: Sales Data
内容: | Month | Sales | | January | $10,000 |...
[2] 文件: test_slides.pptx.md
幻灯片: 第 1 页
内容: # Project Overview This is a test presentation...
```
---
## 概述
基于 Khoj 的本地 RAG 知识库解决方案，支持大规模文件（100G到1T）的全文检索和自然语言查询。通过 MarkItDown 转换 Office 文档，结合云端 LLM API 实现轻量级部署，适合资源受限环境。
---
## 需求背景
### 核心需求
| 需求项 | 具体要求 |
|---|---|
| **数据规模** | 建议小于1T的数据量，例如200GB 本地文件 |
| **文件格式** | xlsx, pptx, pdf, docx, md 等 |
| **检索方式** | 自然语言查询 |
| **大模型** | 云端 API（OpenAI/DeepSeek/Claude/Qwen/Kimi/Minmax） |
| **定位精度** | 来源文件 + 大致位置（工作表/幻灯片） |
| **集成方式** | 封装为 OpenCode Skill |
### 硬件约束
| 约束项 | 配置 |
|---|---|
| **设备** | 常规个人PC，例如MacBook Air M2 |
| **内存** | 8GB+ 可用内存 |
| **剩余空间** | 足够的磁盘空间（文档大小的 25-40%）。例如200G的文件，需要有80GB空闲空间，支持本地向量数据库存储RAG结果。 |
| **本地 LLM** | 无法部署（资源不足） |
---
## 技术架构
### 架构图
```
┌─────────────────────────────────────────────────────────────────┐
│ OpenCode Skill │
│ rag query "搜索内容" --top-k 10 │
│ rag index /path/to/files │
│ rag status │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Khoj API Server │
│ localhost:42110 │
│ • 向量检索 │
│ • 对话生成 │
│ • 文件管理 │
└─────────────────────────┬───────────────────────────────────────┘
│
┌───────────────┴───────────────┐
▼ ▼
┌─────────────────────┐ ┌─────────────────────┐
│ PostgreSQL 数据库 │ │ 云端 LLM API │
│ (嵌入式 pgserver) │ │ 多模型支持 │
│ • 向量存储 │ │ • Chat Model │
│ • 文档索引 │ │ • 对话生成 │
│ • ~50-80GB │ │ • 无本地占用 │
└─────────────────────┘ └─────────────────────┘
```
### 数据流
```
xlsx/pptx → MarkItDown 转换 → Markdown → Khoj 索引 → 向量数据库
↓
用户查询 → 向量检索 → 匹配片段 → 云端 LLM → 自然语言回答
↓
显示来源文件 + 位置
```
### 组件说明
| 组件 | 选择 | 理由 |
|---|---|---|
| **RAG 服务** | Khoj | 成熟（33k stars）、API 友好、内存占用低 |
| **文档转换** | MarkItDown | 微软开源、支持 xlsx/pptx、保留位置信息 |
| **向量数据库** | PostgreSQL（嵌入式） | 成熟稳定、pgvector 向量索引、8GB+ RAM 友好 |
| **Embedding** | 本地模型（sentence-transformers） | 免费、快速、隐私保护 |
| **LLM** | 云端 API | 解放内存压力、性能更好 |
---
## 安装部署
### 环境要求
- Python 3.10+
- macOS / Linux / Windows
- 建议 8GB+ 可用内存
- 足够的磁盘空间（文档大小的 25-40%）
### 平台支持
| 平台 | 支持状态 | 说明 |
|------|----------|------|
| macOS | ✅ 完全支持 | 原生支持，直接使用 |
| Linux | ✅ 完全支持 | 原生支持，直接使用 |
| Windows | ⚠️ 需要 WSL2 | 使用 WSL2 运行 Linux 环境 |
#### Windows 用户：安装 WSL2
**WSL2**（Windows Subsystem for Linux 2）让 Windows 可以直接运行 Linux，无需虚拟机或双系统。
```powershell
# 1. 在 Windows PowerShell（管理员模式）中运行
wsl --install
# 2. 重启电脑后，打开 "Ubuntu" 应用
# 3. 在 Ubuntu 终端中继续以下安装步骤
```
安装 WSL2 后，在 Ubuntu 终端中执行所有后续命令。
### 安装步骤
#### 1. 安装依赖
```bash
# 安装 Khoj
pip install khoj
# 安装 MarkItDown（含 Office 文档支持）
pip install "markitdown[xlsx,pptx]"
```
#### 2. 配置云端 LLM API
```bash
# OpenAI
export OPENAI_API_KEY="sk-xxx"
# DeepSeek（推荐，性价比高）
export OPENAI_API_KEY="sk-xxx"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"
# Anthropic Claude
export ANTHROPIC_API_KEY="sk-xxx"
```
#### 3. 启动 Khoj 服务
```bash
# 嵌入式 PostgreSQL 模式（推荐个人使用）
export USE_EMBEDDED_DB="true"
khoj --anonymous-mode
# 访问 Web UI
open http://localhost:42110
```
---
## 使用指南
### 命令列表
| 命令 | 说明 | 示例 |
|---|---|---|
| `rag start` | 启动 Khoj 服务 | `rag start` |
| `rag stop` | 停止服务 | `rag stop` |
| `rag status` | 查看服务状态 | `rag status` |
| `rag convert <dir>` | 转换 xlsx/pptx 为 Markdown | `rag convert ~/Documents` |
| `rag index <dir>` | 索引文件到知识库 | `rag index ~/Documents/converted` |
| `rag query "<问题>"` | 查询知识库 | `rag query "第三季度销售数据"` |
| `rag clean` | 清理转换后的临时文件 | `rag clean` |
| `rag sync` | 增量同步目录到知识库 | `rag sync ~/Documents` |
| `rag schedule` | 管理定时同步任务 | `rag schedule ~/Documents --enable` |
### 文档转换
```bash
# 转换指定目录下的 xlsx/pptx 文件
markitdown convert ~/Documents/source -o ~/Documents/converted
# 转换单个文件
markitdown convert report.xlsx -o report.md
```
转换结果示例：
**Excel (xlsx)**:
```markdown
## Sheet1
| Name | Age | City |
|---|---|---|
| Alice | 30 | NYC |
| Bob | 25 | LA |
## Sheet2
| Product | Price |
|---|---|
| Apple | $1 |
```
**PowerPoint (pptx)**:
```markdown
<!-- Slide number: 1 -->
# Project Overview
This is the introduction...
<!-- Slide number: 2 -->
## Key Features
- Feature 1
- Feature 2
```
### 知识库索引
#### 方式一：Web UI
1. 打开 http://localhost:42110/config
2. 点击 "Add Content Source"
3. 选择文件夹路径
4. 等待索引完成
#### 方式二：API
```bash
curl -X PATCH "http://localhost:42110/api/content" \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "files=@/path/to/document.md"
```
### 查询示例
```bash
# CLI 查询
khoj query "第三季度的销售数据在哪？"
# API 查询
curl "http://localhost:42110/api/search?q=第三季度销售数据&n=5" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**返回结果示例**：
```
来源文件: Q3_report.xlsx
位置: Sheet1
匹配内容:
| Month | Sales | Growth |
|---|---|---|
| July | $50,000 | +12% |
| August | $55,000 | +10% |
| September | $60,000 | +9% |
来源文件: sales.pptx
位置: Slide 5
匹配内容:
Q3 Sales Summary: Total $165,000
```
---
## 文件格式支持
| 格式 | 支持方式 | 位置信息 | 说明 |
|---|---|---|---|
| **xlsx/xls** | MarkItDown 转换 | ✅ 工作表名称 | 表格数据完整保留 |
| **pptx** | MarkItDown 转换 | ✅ 幻灯片编号 | 文本、表格提取 |
| **pdf** | Khoj 原生支持 | ✅ 页码 | 自动 OCR 扫描版 |
| **docx** | Khoj 原生支持 | ✅ 段落标题 | 完整文档结构 |
| **md/txt** | Khoj 原生支持 | ✅ 文件名 | 最佳支持 |
| **org** | Khoj 原生支持 | ✅ 文件名 | Emacs 用户友好 |
### 不支持的格式
| 格式 | 解决方案 |
|---|---|
| .epub | `pandoc book.epub -o book.md` |
| .html | `pandoc page.html -o page.md` |
| .rtf | `pandoc doc.rtf -o doc.md` |
---
## 空间与性能
### 空间估算
| 项目 | 空间占用 | 说明 |
|---|---|---|
| **原始文件** | 200GB | 保留不变 |
| **转换后 Markdown** | ~20-40GB | 索引后可删除 |
| **Khoj 安装** | ~0.5GB | Python 包 + 本地模型 |
| **向量数据库** | ~50-80GB | 索引文件 |
| **临时占用（最大）** | ~70-120GB | 索引过程中 |
| **最终占用** | ~250-280GB | 删除 Markdown 后 |
### 空间时间线
```
初始状态: 100GB 可用
安装后: 99.5GB 可用（-0.5GB）
转换后: 60-80GB 可用（-20-40GB）
索引完成: 10-30GB 可用（-50-80GB）← 最紧张时刻
删除 Markdown: 50-70GB 可用（+20-40GB）
```
### 性能指标
| 指标 | 数值 | 说明 |
|---|---|---|
| **索引速度** | ~1-2GB/小时 | 常规个人PC |
| **查询响应** | 50-200ms | 向量检索 |
| **对话生成** | 1-3秒 | 取决于云端 API |
| **内存占用** | ~200-500MB | 空闲时 |
| **索引时内存** | ~2-4GB | 取决于文件大小 |
---
## 云端 API 配置
### 支持的 LLM 提供商
| 提供商 | API Key 环境变量 | 模型示例 |
|---|-