rag-skills

LlamaFarm 向け RAG スキル

RAG コンポーネントに特化したパターンとコードレビュー用チェックリストです。

拡張元：python-skills - ここでは、Python のベストプラクティスがすべて適用されます。

コンポーネントの概要

項目	テクノロジー	バージョン
Python	Python	3.11+
ドキュメント処理	LlamaIndex	0.13+
ベクトルストレージ	ChromaDB	1.0+
タスクキュー	Celery	5.5+
埋め込み	Universal/Ollama/OpenAI	複数

ディレクトリ構成

rag/
├── api.py                 # Search and database APIs
├── celery_app.py          # Celery configuration
├── main.py                # Entry point
├── core/
│   ├── base.py            # Document, Component, Pipeline ABCs
│   ├── factories.py       # Component factories
│   ├── ingest_handler.py  # File ingestion with safety checks
│   ├── blob_processor.py  # Binary file processing
│   ├── settings.py        # Pydantic settings
│   └── logging.py         # RAGStructLogger
├── components/
│   ├── embedders/         # Embedding providers
│   ├── extractors/        # Metadata extractors
│   ├── parsers/           # Document parsers (LlamaIndex)
│   ├── retrievers/        # Retrieval strategies
│   └── stores/            # Vector stores (ChromaDB, FAISS)
├── tasks/                 # Celery tasks
│   ├── ingest_tasks.py    # File ingestion
│   ├── search_tasks.py    # Database search
│   ├── query_tasks.py     # Complex queries
│   ├── health_tasks.py    # Health checks
│   └── stats_tasks.py     # Statistics
└── utils/
    └── embedding_safety.py  # Circuit breaker, validation

クイックリファレンス

トピック	ファイル	主なポイント
LlamaIndex	llamaindex.md	ドキュメントの解析、チャンク化、ノードへの変換
ChromaDB	chromadb.md	コレクション、埋め込み、距離メトリクス
Celery	celery.md	タスクのルーティング、エラー処理、ワーカー設定
パフォーマンス	performance.md	バッチ処理、キャッシュ、重複排除

コアパターン

Document データクラス

from dataclasses import dataclass, field
from typing import Any

@dataclass
class Document:
    content: str
    metadata: dict[str, Any] = field(default_factory=dict)
    id: str = field(default_factory=lambda: str(uuid.uuid4()))
    source: str | None = None
    embeddings: list[float] | None = None

コンポーネントの抽象基底クラス

from abc import ABC, abstractmethod

class Component(ABC):
    def __init__(
        self,
        name: str | None = None,
        config: dict[str, Any] | None = None,
        project_dir: Path | None = None,
    ):
        self.name = name or self.__class__.__name__
        self.config = config or {}
        self.logger = RAGStructLogger(__name__).bind(name=self.name)
        self.project_dir = project_dir

    @abstractmethod
    def process(self, documents: list[Document]) -> ProcessingResult:
        pass

検索戦略パターン

class RetrievalStrategy(Component, ABC):
    @abstractmethod
    def retrieve(
        self,
        query_embedding: list[float],
        vector_store,
        top_k: int = 5,
        **kwargs
    ) -> RetrievalResult:
        pass

    @abstractmethod
    def supports_vector_store(self, vector_store_type: str) -> bool:
        pass

サーキットブレーカー付き Embedding

class Embedder(Component):
    DEFAULT_FAILURE_THRESHOLD = 5
    DEFAULT_RESET_TIMEOUT = 60.0

    def __init__(self, ...):
        super().__init__(...)
        self._circuit_breaker = CircuitBreaker(
            failure_threshold=config.get("failure_threshold", 5),
            reset_timeout=config.get("reset_timeout", 60.0),
        )
        self._fail_fast = config.get("fail_fast", True)

    def embed_text(self, text: str) -> list[float]:
        self.check_circuit_breaker()
        try:
            embedding = self._call_embedding_api(text)
            self.record_success()
            return embedding
        except Exception as e:
            self.record_failure(e)
            if self._fail_fast:
                raise EmbedderUnavailableError(str(e)) from e
            return [0.0] * self.get_embedding_dimension()

レビューチェックリストの概要

RAG コードをレビューする際は、以下を確認します。

1. LlamaIndex（優先度：中）

   • チャンク化の設定が適切である
   • 解析中にメタデータが保持される
   • 未対応の形式に対するエラー処理が適切である

2. ChromaDB（優先度：高）

   • クライアントへのアクセスがスレッドセーフである
   • 距離メトリクスが適切に選択されている
   • メタデータの型に互換性がある

3. Celery（優先度：高）

   • タスクが正しいキューにルーティングされる
   • コンテキストを含むエラーログが記録される
   • シリアライズが適切である

4. パフォーマンス（優先度：中）

   • 埋め込みにバッチ処理を使用する
   • 重複排除が有効になっている
   • キャッシュが適切である

grep パターンを含む詳細なチェックリストについては、各トピックのファイルを参照してください。