local-rag

Name: local-rag
Author: nigo81

108stars24forks

How to install local-rag?

nigo81/nigo-skills/local-rag

$npx -y skills add nigo81/nigo-skills --skill local-rag

Installs into the current project.

Summary

本地向量知识库，支持按项目管理文档（docx/doc/pdf/md），语义检索。默认用硅基流动免费 API，零模型安装即可使用。支持多项目隔离、中文制度文档专用切片、Embedding+Rerank 两阶段检索。触发词：知识库、向量检索、RAG、制度检索、文档入库、语义搜索、local rag、搜制度、查条款、文档检索、从文档中搜、语义匹配。即使用户只是说"帮我从这些文件里找到关于XX的规定"或"对比两份制度的差异"，也应使用本 skill。

Files · 1

View on GitHub

SKILL.md

1	# 本地 RAG 知识库
2
3	轻量级本地向量知识库，支持按项目管理文档，语义检索制度条款。
4
5	> 作者: nigo（公众号「逆行的狗」）
6	> 面向财务/审计从业者的 AI 效率工具，有任何问题可关注公众号反馈。
7
8	## 技术栈
9
10	- 切片：Chonkie RecursiveChunker + OverlapRefinery（15% overlap）
11	- 向量库：ChromaDB（persistent，多项目隔离）
12	- 默认 Embedding：硅基流动 BAAI/bge-m3（免费，1024维，8192 tokens）
13	- 默认 Reranker：硅基流动 BAAI/bge-reranker-v2-m3（免费）
14	- 文档解析：textutil（macOS .doc）+ python-docx（.docx）+ PyMuPDF（.pdf）+ MinerU（扫描件）
15	- 可选本地模式：Ollama embedding + Ollama reranker（完全离线）
16
17	## 使用方式
18
19	### CLI（推荐）
20
21	`bin/local-rag` 是独立的 CLI 入口脚本，自动定位 skill 目录，可在任意位置运行。
22
23	```bash
24	# 设置快捷方式（一次性，加到 PATH）
25	export PATH="$HOME/.claude/skills/local-rag/bin:$PATH"
26	# 或创建别名：alias local-rag="$HOME/.claude/skills/local-rag/bin/local-rag"
27
28	# 首次配置（交互式向导）
29	local-rag setup
30
31	# 项目管理
32	local-rag create my-project
33	local-rag delete my-project
34	local-rag list
35
36	# 入库
37	local-rag ingest my-project /path/to/docs
38	local-rag ingest my-project /path/to/file.docx --label "财务制度"
39
40	# 检索
41	local-rag search my-project "消防安全管理"
42	local-rag search my-project "消防安全管理" --rerank --top-k 20
43
44	# 工具
45	local-rag chunk-test /path/to/file.doc
46	local-rag info
47	```
48
49	也可以直接用完整路径：`~/.claude/skills/local-rag/bin/local-rag`
50
51	### Python API
52
53	```python
54	import sys, os
55	# 添加 skill 目录（根据实际安装位置调整）
56	sys.path.insert(0, os.path.expanduser("~/.claude/skills/local-rag"))
57	from src.pipeline import Pipeline
58
59	pipeline = Pipeline()
60
61	# 项目管理
62	pipeline.create_project("my-project")
63	pipeline.list_projects()
64	pipeline.delete_project("my-project")
65
66	# 入库（文件或文件夹）
67	result = pipeline.ingest("my-project", "/path/to/docs")
68
69	# 检索
70	results = pipeline.search("my-project", "消防安全管理", top_k=15)
71
72	# 检索 + Rerank
73	results = pipeline.search_with_rerank("my-project", "消防安全管理", final_k=10)
74
75	# 测试切片
76	result = pipeline.chunk_test("/path/to/file.doc")
77	```
78
79	### MCP Server
80
81	```bash
82	pip install fastmcp
83	python3 ~/.claude/skills/local-rag/mcp_server.py
84	```
85
86	6 个 tool：`create_project` / `delete_project` / `list_projects` / `ingest` / `search` / `rerank_search`
87
88	## Embedding Provider
89
90	\| Provider \| 适用场景 \| 需要什么 \|
91	\|----------\|---------\|---------\|
92	\| siliconflow（默认） \| 大多数场景，免费额度无限量 \| API Key \|
93	\| ollama \| 离线/内网环境 \| Ollama + 模型（~2.5GB） \|
94	\| openai \| 已有 OpenAI 账号 \| API Key \|
95
96	> ⚠️ API Key 安全: 不要把 API Key 直接写在 config.yaml 里！请设置环境变量 `SILICONFLOW_API_KEY`，config.yaml 中用 `${SILICONFLOW_API_KEY}` 引用。
97
98	环境变量 `SILICONFLOW_API_KEY` 设置硅基流动 Key 即可使用默认配置。如果没有 Key，请先到 [硅基流动](https://cloud.siliconflow.cn) 免费注册并创建 API Key。
99
100	### API Key 查找顺序
101
102	当用户没有设置 API Key 时，按以下顺序查找，不要 grep 搜索：
103
104	1. 环境变量 `SILICONFLOW_API_KEY`（`echo $SILICONFLOW_API_KEY` / Windows: `echo %SILICONFLOW_API_KEY%`）
105	2. 配置文件（按平台自动定位）：
106	- macOS: `~/Library/Application Support/local-rag/config.yaml`
107	- Windows: `%LOCALAPPDATA%\local-rag\config.yaml`
108	- Linux: `~/.local/share/local-rag/config.yaml`
109	3. 如果都没有 → 直接引导用户设置，不要到处搜索：
110	```
111	请先设置硅基流动 API Key（免费，注册地址：https://cloud.siliconflow.cn）：
112
113	macOS/Linux:
114	echo 'export SILICONFLOW_API_KEY="sk-xxx"' >> ~/.zshrc && source ~/.zshrc
115
116	Windows (PowerShell):
117	[Environment]::SetEnvironmentVariable("SILICONFLOW_API_KEY", "sk-xxx", "User")
118
119	或运行：local-rag setup
120	```
121
122	## 项目管理
123
124	- 每个项目 = 一个 ChromaDB collection
125	- 项目名只能用英文、数字、点、横线（ChromaDB 限制）
126	- 不同项目的文档完全隔离
127	- 删除项目会删除所有文档和向量
128
129	## 切片策略
130
131	### 中文制度文档（默认）
132	Chonkie RecursiveChunker 三级递归：
133	1. Level 1: 按"第X章"分章节
134	2. Level 2: 按双换行分大段落
135	3. Level 3: 按单换行分条款/段落
136	4. 目标 ~800 字符/chunk，最小 50 字符，15% overlap
137
138	### 通用 Markdown（可选）
139	- 按标题层级（#、##、###）分割
140	- config.yaml 中设 `chunking.strategy: generic`
141
142	## 配置
143
144	配置文件路径（跨平台自动选择）：
145	- macOS: `~/Library/Application Support/local-rag/config.yaml`
146	- Windows: `%LOCALAPPDATA%\local-rag\config.yaml`
147	- Linux: `~/.local/share/local-rag/config.yaml`
148
149	环境变量优先：`SILICONFLOW_API_KEY` / `OPENAI_API_KEY` / `RAG_DATA_DIR` / `RAG_EMBEDDING_MODEL`
150
151	## 数据存储
152
153	默认路径（跨平台自动选择）：
154	- macOS: `~/Library/Application Support/local-rag/`
155	- Windows: `%LOCALAPPDATA%\local-rag\`
156	- Linux: `~/.local/share/local-rag/`
157
158	可通过环境变量 `RAG_DATA_DIR` 或 config.yaml 的 `storage.data_dir` 修改。
159
160	## 前置条件
161
162	### 默认模式（零模型安装）
163	- Python 3.10+
164	- pip install -r requirements.txt
165	- 硅基流动 API Key（注册：https://cloud.siliconflow.cn）
166
167	### 本地模式（可选）
168	- Ollama 运行中，已拉取 `qwen3-embedding:4b`
169	- 无需额外 Python 包
170
171	### 高级离线（极少数需求）
172	- pip install torch transformers
173	- bge-reranker-v2-m3 cross-encoder（~2.3GB）
174
175	## Key Rules
176
177	- 首次使用必须先运行 `local-rag setup` 或手动设置 `SILICONFLOW_API_KEY` 环境变量
178	- 执行任何 CLI 命令前，先用 `local-rag info` 检查配置是否就绪
179	- API Key 只能由用户提供，禁止 grep/搜索文件系统找 key。如果 `local-rag info` 报错"API Key 未设置"，直接引导用户（见上方"API Key 查找顺序"），不要到处 grep
180	- 不要在没有 API key 的情况下继续执行 ingest/search 等命令，必定失败
181	- 首次使用还需安装依赖：`pip install -r ~/.claude/skills/local-rag/requirements.txt`，如果命令报 ImportError，引导用户安装
182	- v3 默认用硅基流动 API，不需要 GPU 或 Ollama
183	- 推荐用 search_with_rerank（top-20 检索 + rerank top-10），给 LLM 足够候选
184	- LLM 必须阅读候选 chunk 的完整内容，不能只看前几行
185	- 由 LLM 从候选文本中做深度语

People who liked this also viewed

6 picks

Type

local-rag

108stars24forks

View on GitHub

How to install local-rag?

nigo81/nigo-skills/local-rag

$npx -y skills add nigo81/nigo-skills --skill local-rag

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# 本地 RAG 知识库
2
3	轻量级本地向量知识库，支持按项目管理文档，语义检索制度条款。
4
5	> 作者: nigo（公众号「逆行的狗」）
6	> 面向财务/审计从业者的 AI 效率工具，有任何问题可关注公众号反馈。
7
8	## 技术栈
9
10	- 切片：Chonkie RecursiveChunker + OverlapRefinery（15% overlap）
11	- 向量库：ChromaDB（persistent，多项目隔离）
12	- 默认 Embedding：硅基流动 BAAI/bge-m3（免费，1024维，8192 tokens）
13	- 默认 Reranker：硅基流动 BAAI/bge-reranker-v2-m3（免费）
14	- 文档解析：textutil（macOS .doc）+ python-docx（.docx）+ PyMuPDF（.pdf）+ MinerU（扫描件）
15	- 可选本地模式：Ollama embedding + Ollama reranker（完全离线）
16
17	## 使用方式
18
19	### CLI（推荐）
20
21	`bin/local-rag` 是独立的 CLI 入口脚本，自动定位 skill 目录，可在任意位置运行。
22
23	```bash
24	# 设置快捷方式（一次性，加到 PATH）
25	export PATH="$HOME/.claude/skills/local-rag/bin:$PATH"
26	# 或创建别名：alias local-rag="$HOME/.claude/skills/local-rag/bin/local-rag"
27
28	# 首次配置（交互式向导）
29	local-rag setup
30
31	# 项目管理
32	local-rag create my-project
33	local-rag delete my-project
34	local-rag list
35
36	# 入库
37	local-rag ingest my-project /path/to/docs
38	local-rag ingest my-project /path/to/file.docx --label "财务制度"
39
40	# 检索
41	local-rag search my-project "消防安全管理"
42	local-rag search my-project "消防安全管理" --rerank --top-k 20
43
44	# 工具
45	local-rag chunk-test /path/to/file.doc
46	local-rag info
47	```
48
49	也可以直接用完整路径：`~/.claude/skills/local-rag/bin/local-rag`
50
51	### Python API
52
53	```python
54	import sys, os
55	# 添加 skill 目录（根据实际安装位置调整）
56	sys.path.insert(0, os.path.expanduser("~/.claude/skills/local-rag"))
57	from src.pipeline import Pipeline
58
59	pipeline = Pipeline()
60
61	# 项目管理
62	pipeline.create_project("my-project")
63	pipeline.list_projects()
64	pipeline.delete_project("my-project")
65
66	# 入库（文件或文件夹）
67	result = pipeline.ingest("my-project", "/path/to/docs")
68
69	# 检索
70	results = pipeline.search("my-project", "消防安全管理", top_k=15)
71
72	# 检索 + Rerank
73	results = pipeline.search_with_rerank("my-project", "消防安全管理", final_k=10)
74
75	# 测试切片
76	result = pipeline.chunk_test("/path/to/file.doc")
77	```
78
79	### MCP Server
80
81	```bash
82	pip install fastmcp
83	python3 ~/.claude/skills/local-rag/mcp_server.py
84	```
85
86	6 个 tool：`create_project` / `delete_project` / `list_projects` / `ingest` / `search` / `rerank_search`
87
88	## Embedding Provider
89
90	\| Provider \| 适用场景 \| 需要什么 \|
91	\|----------\|---------\|---------\|
92	\| siliconflow（默认） \| 大多数场景，免费额度无限量 \| API Key \|
93	\| ollama \| 离线/内网环境 \| Ollama + 模型（~2.5GB） \|
94	\| openai \| 已有 OpenAI 账号 \| API Key \|
95
96	> ⚠️ API Key 安全: 不要把 API Key 直接写在 config.yaml 里！请设置环境变量 `SILICONFLOW_API_KEY`，config.yaml 中用 `${SILICONFLOW_API_KEY}` 引用。
97
98	环境变量 `SILICONFLOW_API_KEY` 设置硅基流动 Key 即可使用默认配置。如果没有 Key，请先到 [硅基流动](https://cloud.siliconflow.cn) 免费注册并创建 API Key。
99
100	### API Key 查找顺序
101
102	当用户没有设置 API Key 时，按以下顺序查找，不要 grep 搜索：
103
104	1. 环境变量 `SILICONFLOW_API_KEY`（`echo $SILICONFLOW_API_KEY` / Windows: `echo %SILICONFLOW_API_KEY%`）
105	2. 配置文件（按平台自动定位）：
106	- macOS: `~/Library/Application Support/local-rag/config.yaml`
107	- Windows: `%LOCALAPPDATA%\local-rag\config.yaml`
108	- Linux: `~/.local/share/local-rag/config.yaml`
109	3. 如果都没有 → 直接引导用户设置，不要到处搜索：
110	```
111	请先设置硅基流动 API Key（免费，注册地址：https://cloud.siliconflow.cn）：
112
113	macOS/Linux:
114	echo 'export SILICONFLOW_API_KEY="sk-xxx"' >> ~/.zshrc && source ~/.zshrc
115
116	Windows (PowerShell):
117	[Environment]::SetEnvironmentVariable("SILICONFLOW_API_KEY", "sk-xxx", "User")
118
119	或运行：local-rag setup
120	```
121
122	## 项目管理
123
124	- 每个项目 = 一个 ChromaDB collection
125	- 项目名只能用英文、数字、点、横线（ChromaDB 限制）
126	- 不同项目的文档完全隔离
127	- 删除项目会删除所有文档和向量
128
129	## 切片策略
130
131	### 中文制度文档（默认）
132	Chonkie RecursiveChunker 三级递归：
133	1. Level 1: 按"第X章"分章节
134	2. Level 2: 按双换行分大段落
135	3. Level 3: 按单换行分条款/段落
136	4. 目标 ~800 字符/chunk，最小 50 字符，15% overlap
137
138	### 通用 Markdown（可选）
139	- 按标题层级（#、##、###）分割
140	- config.yaml 中设 `chunking.strategy: generic`
141
142	## 配置
143
144	配置文件路径（跨平台自动选择）：
145	- macOS: `~/Library/Application Support/local-rag/config.yaml`
146	- Windows: `%LOCALAPPDATA%\local-rag\config.yaml`
147	- Linux: `~/.local/share/local-rag/config.yaml`
148
149	环境变量优先：`SILICONFLOW_API_KEY` / `OPENAI_API_KEY` / `RAG_DATA_DIR` / `RAG_EMBEDDING_MODEL`
150
151	## 数据存储
152
153	默认路径（跨平台自动选择）：
154	- macOS: `~/Library/Application Support/local-rag/`
155	- Windows: `%LOCALAPPDATA%\local-rag\`
156	- Linux: `~/.local/share/local-rag/`
157
158	可通过环境变量 `RAG_DATA_DIR` 或 config.yaml 的 `storage.data_dir` 修改。
159
160	## 前置条件
161
162	### 默认模式（零模型安装）
163	- Python 3.10+
164	- pip install -r requirements.txt
165	- 硅基流动 API Key（注册：https://cloud.siliconflow.cn）
166
167	### 本地模式（可选）
168	- Ollama 运行中，已拉取 `qwen3-embedding:4b`
169	- 无需额外 Python 包
170
171	### 高级离线（极少数需求）
172	- pip install torch transformers
173	- bge-reranker-v2-m3 cross-encoder（~2.3GB）
174
175	## Key Rules
176
177	- 首次使用必须先运行 `local-rag setup` 或手动设置 `SILICONFLOW_API_KEY` 环境变量
178	- 执行任何 CLI 命令前，先用 `local-rag info` 检查配置是否就绪
179	- API Key 只能由用户提供，禁止 grep/搜索文件系统找 key。如果 `local-rag info` 报错"API Key 未设置"，直接引导用户（见上方"API Key 查找顺序"），不要到处 grep
180	- 不要在没有 API key 的情况下继续执行 ingest/search 等命令，必定失败
181	- 首次使用还需安装依赖：`pip install -r ~/.claude/skills/local-rag/requirements.txt`，如果命令报 ImportError，引导用户安装
182	- v3 默认用硅基流动 API，不需要 GPU 或 Ollama
183	- 推荐用 search_with_rerank（top-20 检索 + rerank top-10），给 LLM 足够候选
184	- LLM 必须阅读候选 chunk 的完整内容，不能只看前几行
185	- 由 LLM 从候选文本中做深度语

People who liked this also viewed

6 picks

Type