local-rag-builder（本地 RAG 搭建工具）

一站式本地 RAG 系统搭建工具。支持环境自动检测修复、嵌入模型多源下载、5 种切分策略 + GuardStack 守卫栈 + 后处理子切 + 插件注册、多知识库管理与自动分类规则、可调 Prompt、Web 可视化配置。

两种运行模式：

• 🔌 集成模式（默认） — 纯检索，不调用 LLM。智能体（xxxx 等）根据检索到的 context 自行回答。无需配置 LLM，无额外推理成本。
• 🤖 独立模式 — 检索 + LLM 全链路。rag_standalone.py 直接调用外部 LLM（LM Studio / Ollama / vLLM）完成回答，不经过智能体。用户自行选择平台和模型。

工作流说明（以下 xxxx 代指任意智能体）：

集成模式：

1. 你把文档/链接给 xxxx → xxxx 调用 rag_skill.py 向量化入库
2. 你提问 → xxxx 调用 rag_skill.py --query "..." 检索知识库
3. xxxx 根据检索到的 context 组织回答

独立模式：

1. 你把文档/链接给 xxxx → xxxx 调用 rag_standalone.py --import-file <path> 入库
2. 你提问 → xxxx 调用 rag_standalone.py --query "..."
3. rag_standalone.py 自行检索知识库 → 调用本地 LLM → 输出回答
4. xxxx 仅透传结果，不参与推理

触发场景

• 搭建 RAG — "帮我搭一个本地 RAG 系统"
• 环境检测 — "检查我的 Python 环境能否跑 RAG"
• 下载模型 — "下载一个嵌入模型" / "换个模型源重试"
• 切分文档 — "对这个 Markdown 文件做层级切分"
• 向量检索 — "把这份资料入库，搜索相似内容"
• 知识库管理 — "创建一个知识库" / "把这类资料存入指定库"
• 调整参数 — "更新切分参数" / "改 Prompt 模板"
• 智能体集成 — "根据这份资料回答：xxx"（智能体调用 skill 的集成模式）
• 不触发：纯 LLM 聊天不需要检索、简单问答不需要外部资料

核心能力

📚 渐进式加载：本技能采用渐进式 MD 体系，SKILL.md 为入口（≤230行），详细内容拆分到 references/*.md 按需加载。

渐进式文件索引

快速开始

# 1. 进入技能目录
cd ~/.workbuddy/skills/local-rag-builder

# 2. 运行环境检测（自动修复，建议首次用国内镜像）
python scripts/rag_env_setup.py --auto-install --mirror aliyun      # 国内用户推荐
# python scripts/rag_env_setup.py --auto-install                    # 海外用户/默认
# python scripts/rag_env_setup.py --check-only                      # 仅检测不安装
# python scripts/rag_env_setup.py --cleanup-locks                   # 清理 pip 锁文件

# 3. 下载嵌入模型（交互式选择）
python scripts/embedding_model_manager.py --interactive

# 4. 启动 Web 配置界面
python scripts/rag_web_ui.py

# 5a. [技能模式] 纯检索，供智能体调用（无需 LLM）
python scripts/rag_skill.py --query "问题"
python scripts/rag_skill.py --query "问题" --json          # JSON 输出

# 5b. [独立模式] 检索 + LLM 全链路，需外部 LLM 服务
python scripts/rag_standalone.py                            # 交互式 CLI
python scripts/rag_standalone.py --query "问题"              # 单次问答
python scripts/rag_standalone.py --query "问题" --json       # JSON 输出
python scripts/rag_standalone.py --llm-help                  # 查看 LLM 接入指南

工作流程

1. 环境准备 — rag_env_setup.py 检测并安装依赖
2. 模型下载 — embedding_model_manager.py 下载/校验嵌入模型
3. 文档入库 — text_splitter.py 切分文档 → knowledge_base_manager.py 向量化
4. 模式选择 — 根据用途选择入口
   • 技能模式 → rag_skill.py（纯检索，供智能体调用，无需 LLM）
   • 独立模式 → rag_standalone.py（检索 + LLM 全链路，需外部 LLM）
5. 配置调整 — rag_web_ui.py 提供可视化面板

命令速查

数据目录（skills/.standardization/local-rag-builder/data/）

data/
├── kb/               # 向量数据库目录（每个知识库一个子目录）
│   ├── default/      # 默认知识库
│   ├── art/          # 艺术类资料
│   └── politics/     # 政治类资料
├── models/           # 下载的嵌入模型
├── prompts/          # Prompt 模板文件
├── config/           # 运行时配置
├── output/           # 导出产物
├── logs/             # 执行日志
├── cache/            # 缓存
└── config_templates/ # 用户保存的配置模板

自定义扩展（插件注册）

本技能 v1.0 支持通过代码注册自定义切分策略和守卫。

from text_splitter import register_strategy, register_guard, StrategyPlugin, GuardPlugin, Guard

# 自定义切分策略
def my_splitter(text, my_param=100, **kwargs):
    from langchain_core.documents import Document
    # 自定义切分逻辑
    return [Document(page_content=text)]

register_strategy(StrategyPlugin(
    "my_split", "我的自定义切分", my_splitter,
    config_schema={
        "my_param": {"type": "int", "label": "参数名", "default": 100, "min": 1, "max": 1000},
        "flag": {"type": "bool", "label": "开关", "default": False},
    },
    default_config={"my_param": 100, "flag": False},
))

# 自定义守卫
my_guard = Guard("my_guard", re.compile(r'```special\n[\s\S]*?\n```'))
register_guard(GuardPlugin("my_guard", "保护特殊代码块", my_guard))

注册后自动出现在 Web UI 的下拉列表中，配置表单自动生成。

重要约定

1. Python 版本：建议 3.8-3.11（3.12+ 需测试 chromadb 兼容性）
2. 嵌入模型路径：下载后自动修正真实路径（如 bge-small-zh-v1___5）
3. 知识库隔离：不同资料自动/手动归入不同库
4. 重置：删除 data/ 下对应子目录即可重置相关数据