rlama

RLAMA - ローカル RAG システム

RLAMA（Retrieval-Augmented Language Model Adapter）は、ドキュメントのセマンティック検索に対応した、完全ローカルかつオフラインで動作する RAG を提供します。

このスキルを使用する場面

• ローカルドキュメントからナレッジベースを構築する
• 個人のメモ、研究論文、コードドキュメントを検索する
• データをクラウドに送信せずに、ドキュメントベースの Q&A を行う
• プロジェクトドキュメントをインデックス化し、すばやくセマンティック検索する
• 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 秒）。2 回目以降のクエリは 1 秒未満です。

ローカル LLM クエリ（フォールバック時のみ）

Claude が処理に関与しない場合（例：スタンドアロンの CLI 使用、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

外部 LLM による合成（任意。チャンクを取得し、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 経由）
(none needed)	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）では、厳密なプロンプトと最大 4096 トークンを使用する qwen3.5:9b が使われます。これは、複数ドキュメントにまたがる複雑な合成に最適なローカルの選択肢です。

初回実行時に埋め込みキャッシュが構築されます（3K チャンクで約 30 秒、25K チャンクで約 10 分）。2 回目以降のクエリは 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 サーバー

プログラムからアクセスできる API サーバーとして RLAMA を実行します。

# 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 フラグ）では、厳格な研究品質のプロンプト（通常はクラウドプロバイダー専用）を使用し、ローカルの Ollama で統合するために qwen3.5:9b を使用します。これにより、マシンからデータを外部に出すことなく、研究品質の引用付き回答が得られます。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
• ウェブ：.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

ログファイルの形式

ログは ~/.rlama/logs/rlama.log に JSON Lines 形式で書き込まれます。

{"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 を参照してください。