rlama

RLAMA - 本地 RAG 系统

RLAMA（检索增强语言模型适配器）可为文档语义搜索提供完全本地、离线的 RAG。

何时使用此技能

• 根据本地文档构建知识库
• 搜索个人笔记、研究论文或代码文档
• 基于文档进行问答，无需将数据发送到云端
• 为项目文档建立索引，以便快速进行语义查找
• 创建可搜索的 PDF、Markdown 或代码文件档案

先决条件

RLAMA 需要在本地运行 Ollama：

# Verify Ollama is running
ollama list

# If not running, start it
brew services start ollama  # macOS
# or: ollama serve

快速参考

查询 RAG（默认：仅检索）

默认情况下始终使用仅检索模式。 Claude 综合生成答案的能力远胜于本地 7B 模型。原始文本块可为 Claude 提供直接证据，供其推理和引用。

# DEFAULT: Retrieve top 10 chunks — Claude reads and synthesizes
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query"

# More chunks for broad queries
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" -k 20

# JSON output for programmatic use
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --json

# Force rebuild embedding cache
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --rebuild-cache

# List RAGs with cache status
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py --list

每个集合首次运行时都会构建嵌入缓存（4K 个文本块约需 60 秒）。后续查询耗时 <1 秒。

本地大模型查询（仅作备用）

仅当 Claude 不参与流程时（例如，独立使用命令行、cron 作业、脚本），才使用 rlama run：

# Local model generates the answer (weaker than Claude synthesis)
rlama run <rag-name> --query "your question here"

# With more context chunks
rlama run <rag-name> --query "explain the authentication flow" --context-size 30

# Show source documents
rlama run <rag-name> --query "what are the API endpoints?" --show-context

脚本封装，输出更简洁：

python3 ~/.claude/skills/rlama/scripts/rlama_query.py <rag-name> "your query"
python3 ~/.claude/skills/rlama/scripts/rlama_query.py my-docs "what is the main idea?" --show-sources

外部大模型综合生成（可选——检索文本块并通过 OpenRouter、TogetherAI、Ollama 或任何兼容 OpenAI 的端点进行综合生成）：

# Synthesize via OpenRouter (auto-detected from model with /)
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --synthesize --synth-model anthropic/claude-sonnet-4

# Synthesize via TogetherAI
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --synthesize --provider togetherai

# Synthesize via local Ollama (fully offline, uses research-grade system prompt)
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --synthesize --provider ollama

# Synthesize via custom endpoint
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag-name> "your query" --synthesize --endpoint https://my-api.com/v1/chat/completions

综合生成环境变量：

变量	提供商
OPENROUTER_API_KEY	OpenRouter（默认，优先自动检测）
TOGETHER_API_KEY	TogetherAI
SYNTH_API_KEY	自定义端点（通过 --endpoint）
(无需任何变量)	Ollama（本地，无需身份验证）

提供商自动检测：包含 / 的模型名称 → OpenRouter，否则 → TogetherAI。若检测不到，则回退到已设置 API 密钥对应的提供商。

质量等级：

等级	方法	质量	延迟	默认？
最佳	仅检索 → Claude 综合生成	综合能力最强	检索约 1 秒	是
良好	--synthesize --synth-model anthropic/claude-sonnet-4	表现强，带引用	约 3 秒
尚可	--synthesize --provider togetherai（Llama 70B）	事实性内容表现可靠	约 2 秒
推理	--synthesize --reasoning（Qwen 3.5 9B）	本地表现强，带引用	约 8 秒
本地	--synthesize --provider ollama（Qwen 2.5 7B）	基础，可能会表达不确定	约 5 秒
基线	rlama_query.py（RLAMA 内置）	最弱，无法控制提示词	约 3 秒

小型本地模型（7B）使用针对 Qwen 调优的提示词（结构化输出、避免模棱两可、识别领域关键词）。云端提供商使用严格的研究级提示词，并强制要求引用。推理模式（--reasoning）使用 qwen3.5:9b、严格提示词和 4096 个最大令牌，是处理复杂跨文档综合任务的最佳本地选项。

首次运行会构建嵌入缓存（3K 个文本块约需 30 秒，25K 个文本块约需 10 分钟）。后续查询耗时 <1 秒。大型 RAG 使用增量检查点；如果 Ollama 在构建过程中崩溃，重新运行即可从上一个检查点继续。为确保不超出嵌入模型的上下文窗口，每个文本块都会截断至 5K 个字符。

基准测试：

# Retrieval quality only
python3 ~/.claude/skills/rlama/scripts/rlama_bench.py <rag-name> --retrieval-only

# Full synthesis benchmark (8 test cases)
python3 ~/.claude/skills/rlama/scripts/rlama_bench.py <rag-name> --provider ollama --verbose

# Single test case
python3 ~/.claude/skills/rlama/scripts/rlama_bench.py <rag-name> --provider ollama --case 0

# JSON output for analysis
python3 ~/.claude/skills/rlama/scripts/rlama_bench.py <rag-name> --provider ollama --json

评分维度：检索精确度、主题覆盖度、依据充分性、直接性（避免模棱两可）和综合评分（0-100）。

创建 RAG

将文件夹中的文档编入索引，创建新的 RAG 系统：

# Basic creation (uses llama3.2 by default)
rlama rag llama3.2 <rag-name> <folder-path>

# Examples
rlama rag llama3.2 my-notes ~/Notes
rlama rag llama3.2 project-docs ./docs
rlama rag llama3.2 research-papers ~/Papers

# With exclusions
rlama rag llama3.2 codebase ./src --exclude-dir=node_modules,dist,.git --exclude-ext=.log,.tmp

# Only specific file types
rlama rag llama3.2 markdown-docs ./docs --process-ext=.md,.txt

# Custom chunking strategy
rlama rag llama3.2 my-rag ./docs --chunking=semantic --chunk-size=1500 --chunk-overlap=300

分块策略：

• hybrid（默认）- 结合语义分块和固定长度分块
• semantic - 遵循文档结构（段落、章节）
• fixed - 按固定字符数分块
• hierarchical - 保留文档层级结构

列出 RAG 系统

# List all RAGs
rlama list

# List documents in a specific RAG
rlama list-docs <rag-name>

# Inspect chunks (debugging)
rlama list-chunks <rag-name> --document=filename.pdf

管理文档

向现有 RAG 添加文档：

rlama add-docs <rag-name> <folder-or-file>

# Examples
rlama add-docs my-notes ~/Notes/new-notes
rlama add-docs research ./papers/new-paper.pdf

移除文档：

rlama remove-doc <rag-name> <document-id>

# Document ID is typically the filename
rlama remove-doc my-notes old-note.md
rlama remove-doc research outdated-paper.pdf

# Force remove without confirmation
rlama remove-doc my-notes old-note.md --force

删除 RAG

rlama delete <rag-name>

# Or manually remove the data directory
rm -rf ~/.rlama/<rag-name>

高级功能

网页抓取

根据网站内容创建 RAG：

# Crawl a website and create RAG
rlama crawl-rag llama3.2 docs-rag https://docs.example.com

# Add web content to existing RAG
rlama crawl-add-docs my-rag https://blog.example.com

监视目录

文件发生更改时自动更新 RAG：

# Enable watching
rlama watch <rag-name> <folder-path>

# Check for new files manually
rlama check-watched <rag-name>

# Disable watching
rlama watch-off <rag-name>

监视网站

监控网站内容更新：

rlama web-watch <rag-name> https://docs.example.com
rlama check-web-watched <rag-name>
rlama web-watch-off <rag-name>

重排序

通过重排序提升结果相关性：

# Add reranker to existing RAG
rlama add-reranker <rag-name>

# Configure reranker weight (0-1, default 0.7)
rlama update-reranker <rag-name> --reranker-weight=0.8

# Disable reranking
rlama rag llama3.2 my-rag ./docs --disable-reranker

API 服务

将 RLAMA 作为 API 服务运行，以便通过程序访问：

# Start API server
rlama api --port 11249

# Query via API
curl -X POST http://localhost:11249/rag \
  -H "Content-Type: application/json" \
  -d '{
    "rag_name": "my-docs",
    "prompt": "What are the key points?",
    "context_size": 20
  }'

模型管理

# Update the model used by a RAG
rlama update-model <rag-name> <new-model>

# Example: Switch to a more powerful model
rlama update-model my-rag deepseek-r1:8b

# Use Hugging Face models
rlama rag hf.co/username/repo my-rag ./docs
rlama rag hf.co/username/repo:Q4_K_M my-rag ./docs

# Use OpenAI models (requires OPENAI_API_KEY)
export OPENAI_API_KEY="your-key"
rlama rag gpt-4-turbo my-openai-rag ./docs

配置

数据目录

默认情况下，RLAMA 将数据存储在 ~/.rlama/。使用 --data-dir 更改此设置：

# Use custom data directory
rlama --data-dir=/path/to/custom list
rlama --data-dir=/projects/rag-data rag llama3.2 project-rag ./docs

# Or set via environment (add to ~/.zshrc)
export RLAMA_DATA_DIR="/path/to/custom"

Ollama 配置

# Custom Ollama host
rlama --host=192.168.1.100 --port=11434 run my-rag

# Or via environment
export OLLAMA_HOST="http://192.168.1.100:11434"

默认模型

该技能默认使用 qwen2.5:7b（于 2026 年 1 月从 llama3.2 更改而来）。要使用旧版模式：

# Use the old llama3.2 default
python3 ~/.claude/skills/rlama/scripts/rlama_manage.py create my-rag ./docs --legacy

# Per-command model override
rlama rag deepseek-r1:8b my-rag ./docs

# For queries
rlama run my-rag --query "question" -m deepseek-r1:8b

推荐模型：

模型	大小	最适合
qwen2.5:7b	7B	默认模型——适用于快速 RAG 查询（推荐）
qwen3.5:9b	9B	推理模式——更深入的综合分析，严格引用（--reasoning）
llama3.2	3B	快速，旧版默认模型（使用 --legacy）
deepseek-r1:8b	8B	复杂问题
llama3.3:70b	70B	最高质量（速度较慢）

推理模式（--reasoning 标志）使用 qwen3.5:9b 通过本地 Ollama 进行综合分析，并采用严格的研究级提示词（通常仅用于云服务提供商）。无需离开本机，即可获得研究级别且附带引用的答案。通过 RLAMA_REASONING_MODEL 环境变量指定其他模型。

# Reasoning mode — complex cross-document synthesis (think OFF, fast)
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag> "complex query" --synthesize --reasoning

# Reasoning mode with thinking (chain-of-thought, slower but deeper)
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag> "complex query" --synthesize --reasoning --think

# Equivalent explicit invocation
python3 ~/.claude/skills/rlama/scripts/rlama_retrieve.py <rag> "query" --synthesize --provider ollama --synth-model qwen3.5:9b

标志	模型	思考	提示词	最大令牌数	超时
(默认)	qwen2.5:7b	关闭	轻量（避免模棱两可）	2048	120s
--reasoning	qwen3.5:9b	关闭	严格（附带引用）	4096	300s
--reasoning --think	qwen3.5:9b	开启	严格（附带引用）	4096	300s

思考模式会在回答前生成内部思维链推理。思考文本会包含在 JSON 输出中（synthesis.thinking 字段），但不会在纯文本模式下打印。适用于存在歧义的跨文档分析场景，此时你希望查看模型的推理过程。

支持的文件类型

RLAMA 可索引以下格式：

• 文本：.txt、.md、.markdown
• 文档：.pdf、.docx、.doc
• 代码：.py、.js、.ts、.go、.rs、.java、.rb、.cpp、.c、.h
• 数据：.json、.yaml、.yml、.csv
• Web：.html、.htm
• Org-mode：.org

示例工作流

个人知识库

# Create from multiple folders
rlama rag llama3.2 personal-kb ~/Documents
rlama add-docs personal-kb ~/Notes
rlama add-docs personal-kb ~/Downloads/papers

# Query
rlama run personal-kb --query "what did I write about project management?"

代码文档

# Index project docs
rlama rag llama3.2 project-docs ./docs ./README.md

# Query architecture
rlama run project-docs --query "how does authentication work?" --context-size 25

研究论文

# Create research RAG
rlama rag llama3.2 papers ~/Papers --exclude-ext=.bib

# Add specific paper
rlama add-docs papers ./new-paper.pdf

# Query with high context
rlama run papers --query "what methods are used for evaluation?" --context-size 30

交互式向导

通过引导创建 RAG：

rlama wizard

弹性索引（跳过问题文件）

对于包含混合内容的文件夹，其中某些文件可能超出嵌入上下文限制（例如大型 PDF），请使用逐个处理文件并跳过失败项的弹性脚本：

# Create RAG, skipping files that fail
python3 ~/.claude/skills/rlama/scripts/rlama_resilient.py create my-rag ~/Documents

# Add to existing RAG, skipping failures
python3 ~/.claude/skills/rlama/scripts/rlama_resilient.py add my-rag ~/MoreDocs

# With docs-only filter
python3 ~/.claude/skills/rlama/scripts/rlama_resilient.py create research ~/Papers --docs-only

# With legacy model
python3 ~/.claude/skills/rlama/scripts/rlama_resilient.py create my-rag ~/Docs --legacy

该脚本会报告已添加的文件，以及因错误而跳过的文件。

进度监控

使用日志系统实时监控长时间运行的 RLAMA 操作。

跟踪日志文件

# Watch all operations in real-time
tail -f ~/.rlama/logs/rlama.log

# Filter by RAG name
tail -f ~/.rlama/logs/rlama.log | grep my-rag

# Pretty-print with jq
tail -f ~/.rlama/logs/rlama.log | jq -r '"\(.ts) [\(.cat)] \(.msg)"'

# Show only progress updates
tail -f ~/.rlama/logs/rlama.log | jq -r 'select(.data.i) | "\(.ts) [\(.cat)] \(.data.i)/\(.data.total) \(.data.file // .data.status)"'

检查操作状态

# Show active operations
python3 ~/.claude/skills/rlama/scripts/rlama_status.py

# Show recent completed operations
python3 ~/.claude/skills/rlama/scripts/rlama_status.py --recent

# Show both active and recent
python3 ~/.claude/skills/rlama/scripts/rlama_status.py --all

# Follow mode (formatted tail -f)
python3 ~/.claude/skills/rlama/scripts/rlama_status.py --follow

# JSON output
python3 ~/.claude/skills/rlama/scripts/rlama_status.py --json

日志文件格式

日志以 JSON Lines 格式写入 ~/.rlama/logs/rlama.log：

{"ts": "2026-02-03T12:34:56.789", "level": "info", "cat": "INGEST", "msg": "Progress 45/100", "data": {"op_id": "ingest_abc123", "i": 45, "total": 100, "file": "doc.pdf", "eta_sec": 85}}

操作状态

活动操作和最近的操作会记录在 ~/.rlama/logs/operations.json 中：

{
  "active": {
    "ingest_abc123": {
      "type": "ingest",
      "rag_name": "my-docs",
      "started": "2026-02-03T12:30:00",
      "processed": 45,
      "total": 100,
      "eta_sec": 85
    }
  },
  "recent": [...]
}

故障排除

“未找到 Ollama”

# Check Ollama status
ollama --version
ollama list

# Start Ollama
brew services start ollama  # macOS
ollama serve                # Manual start

“未找到模型”

# Pull the required model
ollama pull llama3.2
ollama pull nomic-embed-text  # Embedding model

索引速度慢

• 使用更小的嵌入模型
• 排除大型二进制文件：--exclude-ext=.bin,.zip,.tar
• 排除构建目录：--exclude-dir=node_modules,dist,build

查询结果不佳

1. 增大上下文大小：--context-size=30
2. 使用更好的模型：-m deepseek-r1:8b
3. 使用语义分块重新索引：--chunking=semantic
4. 启用重排：rlama add-reranker <rag-name>

索引损坏

# Delete and recreate
rm -rf ~/.rlama/<rag-name>
rlama rag llama3.2 <rag-name> <folder-path>

CLI 参考

完整命令参考：

rlama --help
rlama <command> --help

或者参阅 references/rlama-commands.md 获取完整文档。