SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillslocal-rag

local-rag

Agents & models

View repository

Updated 10-16 01:38

About this skill

Local RAG Knowledge Base

Lightweight local vector knowledge base, supports document management by project, semantic retrieval of institutional clauses.

Author: nigo (WeChat public account "逆行的狗") AI efficiency tools for finance/audit practitioners. If you have any questions, follow the WeChat public account to give feedback.

Tech Stack

  • Chunking: Chonkie RecursiveChunker + OverlapRefinery (15% overlap)
  • Vector store: ChromaDB (persistent, multi-project isolation)
  • Default Embedding: SiliconFlow BAAI/bge-m3 (free, 1024 dimensions, 8192 tokens)
  • Default Reranker: SiliconFlow BAAI/bge-reranker-v2-m3 (free)
  • Document parsing: textutil (macOS .doc) + python-docx (.docx) + PyMuPDF (.pdf) + MinerU (scanned documents)
  • Optional local mode: Ollama embedding + Ollama reranker (fully offline)

Usage

CLI (recommended)

bin/local-rag is a standalone CLI entry script that automatically locates the skill directory and can be run from any location.

# 设置快捷方式（一次性，加到 PATH）
export PATH="$HOME/.claude/skills/local-rag/bin:$PATH"
# 或创建别名：alias local-rag="$HOME/.claude/skills/local-rag/bin/local-rag"

# 首次配置（交互式向导）
local-rag setup

# 项目管理
local-rag create my-project
local-rag delete my-project
local-rag list

# 入库
local-rag ingest my-project /path/to/docs
local-rag ingest my-project /path/to/file.docx --label "财务制度"

# 检索
local-rag search my-project "消防安全管理"
local-rag search my-project "消防安全管理" --rerank --top-k 20

# 工具
local-rag chunk-test /path/to/file.doc
local-rag info

You can also use the full path directly:~/.claude/skills/local-rag/bin/local-rag

Python API

import sys, os
# 添加 skill 目录（根据实际安装位置调整）
sys.path.insert(0, os.path.expanduser("~/.claude/skills/local-rag"))
from src.pipeline import Pipeline

pipeline = Pipeline()

# 项目管理
pipeline.create_project("my-project")
pipeline.list_projects()
pipeline.delete_project("my-project")

# 入库（文件或文件夹）
result = pipeline.ingest("my-project", "/path/to/docs")

# 检索
results = pipeline.search("my-project", "消防安全管理", top_k=15)

# 检索 + Rerank
results = pipeline.search_with_rerank("my-project", "消防安全管理", final_k=10)

# 测试切片
result = pipeline.chunk_test("/path/to/file.doc")

MCP Server

pip install fastmcp
python3 ~/.claude/skills/local-rag/mcp_server.py

6 tools:create_project / delete_project / list_projects / ingest / search / rerank_search

Embedding Provider

Provider Use Case What's Needed
siliconflow(default) Most scenarios, unlimited free quota API Key
ollama Offline/intranet environment Ollama + model (~2.5GB)
openai Already have an OpenAI account API Key

⚠️ API Key Security: Do not write the API Key directly in config.yaml! Please set the environment variable SILICONFLOW_API_KEY, and reference it in config.yaml using ${SILICONFLOW_API_KEY} .

Environment variable SILICONFLOW_API_KEY Set the SiliconFlow Key to use the default configuration. If you don't have a Key, please first go to SiliconFlow to register for free and create an API Key.

API Key Lookup Order

When the user has not set an API Key, look it up in the following order,do not grep search：

  1. Environment variable SILICONFLOW_API_KEY（echo $SILICONFLOW_API_KEY / Windows: echo %SILICONFLOW_API_KEY%）
  2. Config file (automatically located by platform):
    • macOS: ~/Library/Application Support/local-rag/config.yaml
    • Windows: %LOCALAPPDATA%\local-rag\config.yaml
    • Linux: ~/.local/share/local-rag/config.yaml
  3. If neither exists → directly guide the user to set it, do not search everywhere: 
    请先设置硅基流动 API Key（免费，注册地址：https://cloud.siliconflow.cn）：

macOS/Linux:
echo 'export SILICONFLOW_API_KEY="sk-xxx"' >> ~/.zshrc && source ~/.zshrc

Windows (PowerShell):
[Environment]::SetEnvironmentVariable("SILICONFLOW_API_KEY", "sk-xxx", "User")

或运行：local-rag setup

Project Management

  • Each project = one ChromaDB collection
  • Project names can only use English letters, numbers, dots, and hyphens (ChromaDB limitation)
  • Documents of different projects are completely isolated
  • Deleting a project will delete all documents and vectors

Chunking Strategy

Chinese institutional documents (default)

Chonkie RecursiveChunker three-level recursion:

  1. Level 1: Split by "Chapter X"
  2. Level 2: Split by double line breaks into large paragraphs
  3. Level 3: Split by single line breaks into clauses/paragraphs
  4. Target ~800 characters/chunk, minimum 50 characters, 15% overlap

General Markdown (optional)

  • Split by heading levels (#, ##, ###)
  • Set in config.yaml chunking.strategy: generic

Configuration

Config file path (automatically selected across platforms):

  • macOS: ~/Library/Application Support/local-rag/config.yaml
  • Windows: %LOCALAPPDATA%\local-rag\config.yaml
  • Linux: ~/.local/share/local-rag/config.yaml

Environment variables take priority:SILICONFLOW_API_KEY / OPENAI_API_KEY / RAG_DATA_DIR / RAG_EMBEDDING_MODEL

Data storage

Default path (automatically selected across platforms):

  • macOS: ~/Library/Application Support/local-rag/
  • Windows: %LOCALAPPDATA%\local-rag\
  • Linux: ~/.local/share/local-rag/

Can be set via the environment variable RAG_DATA_DIR or the storage.data_dir in config.yaml.

Prerequisites

Default mode (zero model installation)

Local mode (optional)

  • Ollama is running, and qwen3-embedding:4b
  • has been pulled. No additional Python packages required

Advanced offline (rarely needed)

  • pip install torch transformers
  • bge-reranker-v2-m3 cross-encoder（~2.3GB）

Key Rules

  • On first use, you must first run local-rag setup or manually set the SILICONFLOW_API_KEY environment variable
  • Before executing any CLI command, first use local-rag info to check whether the configuration is ready
  • The API Key can only be provided by the user; grep/search the filesystem for the key is prohibited. If local-rag info reports "API Key not set", directly guide the user (see "API Key lookup order" above), do not grep everywhere
  • Do not continue executing without an API key commands such as ingest/search, they will definitely fail
  • On first use, dependencies also need to be installed：pip install -r ~/.claude/skills/local-rag/requirements.txt. If the command reports ImportError, guide the user to install them
  • v3 uses the SiliconFlow API by default, no GPU or Ollama required
  • It is recommended to use search_with_rerank (top-20 retrieval + rerank top-10), giving the LLM enough candidates
  • The LLM must read thecomplete contentof the candidate chunks, and must not only look at the first few lines
  • The LLM performs deep semantic matching from the candidate texts to precisely locate clauses
  • The key to the LLM's judgment: not choosing "the most textually similar", but choosing "the one that governs the same matter"
  • Vector retrieval cannot determine "no counterpart", so a second judgment by the LLM is needed
  • .doc files should preferably be converted with macOS textutil; on non-macOS, fall back to python-docx
  • Scanned PDFs (less than 50 characters of text per page) are automatically processed with MinerU
  • Environment variable RAG_EMBEDDING_MODEL can switch models

Pitfall log

  1. ChromaDB 1.3.5 list_collections() returns a Collection object, requires .name
  2. Chonkie RecursiveLevel cannot set both delimiters and whitespace
  3. The Ollama reranker (chat API) outputs garbled text; v3 switched to embedding-based cosine similarity
  4. Embedding cosine similarity for rerank has limited effectiveness, but it is better than nothing; cross-encoder is more accurate
  5. Ollama /api/embed returns {"embeddings": [[...]]} not {"embedding": [...]}
  6. The SiliconFlow reranker is a Cohere-style API, not OpenAI format