llm-integration

LLM 統合

本番アプリケーションに LLM を統合するためのパターンです。ツールの使用、ストリーミング、ローカル推論、ファインチューニングを扱います。各カテゴリには個別のルールファイルがあり、必要に応じて rules/ から読み込まれます。

クイックリファレンス

カテゴリ	ルール	影響度	使用する場面
関数呼び出し	3	重大	ツール定義、並列実行、入力検証
ストリーミング	3	高	SSE エンドポイント、構造化ストリーミング、バックプレッシャー処理
ローカル推論	3	高	Ollama のセットアップ、モデル選択、GPU 最適化
ファインチューニング	3	高	LoRA/QLoRA トレーニング、データセットの準備、評価
コンテキスト最適化	2	高	ウィンドウ管理、圧縮、キャッシュ、予算の拡張
評価	2	高	LLM による評価、RAGAS メトリクス、品質ゲート、ベンチマーク
プロンプトエンジニアリング	4	高	CoT、少数ショット、バージョン管理、DSPy 最適化、ReAct、コスト最適化

合計：7 カテゴリにわたる 20 個のルール

クイックスタート

# Function calling: strict mode tool definition
tools = [{
    "type": "function",
    "function": {
        "name": "search_documents",
        "description": "Search knowledge base",
        "strict": True,
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "Search query"},
                "limit": {"type": "integer", "description": "Max results"}
            },
            "required": ["query", "limit"],
            "additionalProperties": False
        }
    }
}]

# Streaming: SSE endpoint with FastAPI
@app.get("/chat/stream")
async def stream_chat(prompt: str):
    async def generate():
        async for token in async_stream(prompt):
            yield {"event": "token", "data": token}
        yield {"event": "done", "data": ""}
    return EventSourceResponse(generate())

# Local inference: Ollama with LangChain
llm = ChatOllama(
    model="deepseek-r1:70b",
    base_url="http://localhost:11434",
    temperature=0.0,
    num_ctx=32768,
)

# Fine-tuning: QLoRA with Unsloth
model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B",
    max_seq_length=2048, load_in_4bit=True,
)
model = FastLanguageModel.get_peft_model(model, r=16, lora_alpha=32)

関数呼び出し

LLM が外部ツールを使い、構造化データを返せるようにします。信頼性を高めるには、厳格モードのスキーマ（2026 年のベストプラクティス）を使用してください。Claude では、プロンプトキャッシュを維持するため、ターン間で tools 配列を安定させてください。サブセットを入れ替えるのではなく、インラインの tool_addition（ベータ版 inline-tools-2026-09-15。Claude API のみ対応。Sonnet 5.5 では利用可能ですが、Sonnet 5 では利用できません）を使って、セッション中にツールを追加してください（https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes）。大規模なツールセットでは、遅延読み込みしないツール検索ツールを 1 つ用意し、残りのツールに defer_loading: true を設定してください。defer_loading だけを設定することはできません（リクエスト内のすべてのツールを遅延させることはできません）。強制的な tool_choice（any または名前を指定したツール）は、Sonnet 5.5、Opus 5.5、Fable 5.1、Mythos 5.1 で 400 エラーを返します。strict: true を指定したツールで auto を使用してください。すべての入力を Pydantic/Zod で検証し、エラーはツールの結果として返してください。

• calling-tool-definition.md -- 厳格モードのスキーマ、OpenAI/Anthropic 形式、LangChain バインディング
• calling-parallel.md -- ツールの並列実行、asyncio.gather、厳格モードの制約
• calling-validation.md -- 入力検証、エラー処理、ツール実行ループ

ストリーミング

UX を向上させるため、LLM の応答をリアルタイムで配信します。ウェブには SSE、双方向通信には WebSocket を使用します。上限付きキューでバックプレッシャーを処理してください。

• streaming-sse.md -- FastAPI の SSE エンドポイント、フロントエンドのコンシューマー、非同期イテレーター
• streaming-structured.md -- ツール呼び出しを伴うストリーミング、部分的な JSON の解析、チャンクの蓄積
• streaming-backpressure.md -- バックプレッシャー処理、上限付きバッファー、キャンセル

ローカル推論

コスト削減（クラウドと比べて 93％）、プライバシーの保護、オフライン開発のために、Ollama で LLM をローカル実行します。モデルを事前にウォームアップし、クラウドとローカルを切り替えるにはプロバイダーファクトリーを使用してください。

• local-ollama-setup.md -- インストール、モデルの取得、環境設定
• local-model-selection.md -- タスク別のモデル比較、ハードウェア構成、量子化
• local-gpu-optimization.md -- Apple Silicon のチューニング、キープアライブ、CI 統合

ファインチューニング

パラメーター効率の高い手法で LLM をカスタマイズします。プロンプトエンジニアリングと RAG を十分に試した後に限り、ファインチューニングしてください。品質の高い例が 1000 件以上必要です。

• tuning-lora.md -- LoRA/QLoRA の設定、Unsloth によるトレーニング、アダプターのマージ
• tuning-dataset-prep.md -- 合成データの生成、品質検証、重複排除
• tuning-evaluation.md -- DPO によるアラインメント、評価指標、アンチパターン

コンテキスト最適化

コンテキストウィンドウ、圧縮、注意機構を考慮した配置を管理します。タスクあたりのトークン数を最適化してください。

• context-window-management.md -- 5 層アーキテクチャ、アンカー付き要約、圧縮のトリガー
• context-caching.md -- ジャストインタイム読み込み、予算の拡張、プローブ評価、CC 2.1.32+

評価

多次元スコアリング、品質ゲート、ベンチマークを使って、LLM の出力を評価します。

• evaluation-metrics.md -- LLM による評価、RAGAS メトリクス、ハルシネーションの検出
• evaluation-benchmarks.md -- 品質ゲート、バッチ評価、ペアワイズ比較

プロンプトエンジニアリング

本番環境の LLM アプリケーション向けに、プロンプトを設計、バージョン管理、最適化します。

• prompt-design.md -- Chain-of-Thought、Few-shot 学習、パターン選択ガイド
• prompt-testing.md -- Langfuse によるバージョン管理、DSPy による最適化、A/B テスト、自己整合性
• prompt-react-pattern.md -- ツールを使うエージェント向けの ReAct ループ、思考・行動・観察の形式
• prompt-optimization.md -- トークン削減、コスト最適化、モデルの階層化、プロンプト仕様の形式

上流ドキュメントの対象範囲（再記載しない）

これらのトピックは各ベンダーの公式ドキュメントで扱われています。このスキルでは解説せず、公式ドキュメントを参照します。上記のルールでは、私たち独自の最低基準、上限、失敗から得た知見のみを扱います。これらに関する差分はすべて references/ork-delta.md に記載しています。

トピック	公式ドキュメント
Strict モードのツールスキーマ、構造化出力	https://platform.openai.com/docs/guides/function-calling
Anthropic の input_schema / tool_use	https://docs.claude.com/en/docs/agents-and-tools/tool-use/overview
SSE クライアントの仕組み、再接続、キャンセル	https://developer.mozilla.org/en-US/docs/Web/API/EventSource
LoRA / QLoRA の設定、ターゲットモジュール、アダプターのマージ	https://huggingface.co/docs/peft/developer_guides/lora
Unsloth のトレーニングループ、4-bit 読み込み	https://docs.unsloth.ai/get-started/fine-tuning-llms-guide
DPO、選好ペア、beta の調整、RLHF との比較	https://huggingface.co/docs/trl/dpo_trainer
SFT データセットの形式（Alpaca、ChatML）	https://huggingface.co/docs/trl/sft_trainer
データセットの重複排除に使う埋め込み類似度	https://sbert.net/
ファインチューニング、プロンプト、RAG の選択フレームワーク	https://platform.openai.com/docs/guides/optimizing-llm-accuracy
ベンダーのトークン料金（ここにハードコードしないこと）	https://platform.openai.com/docs/pricing

補助ファイル

• references/ork-delta.md -- 私たち独自の差分：失敗から得た知見、内部の上限、廃止済みファイルの由来
• references/model-selection.md -- タスクとハードウェア別のローカルモデル比較
• scripts/create-lora-config.md -- モデルタイプの自動検出に対応した LoRA 設定のひな形

重要な決定事項

決定事項	推奨事項
ツールスキーマモード	strict: true（2026 年のベストプラクティス）
ツール数	最初におよそ 5～15 個を読み込み、残りは遅延読み込みされないツール検索ツール経由で取得します
ストリーミングプロトコル	Web には SSE、双方向通信には WebSocket
バッファーサイズ	50～200 トークン
ローカルモデル（推論）	deepseek-r1:70b
ローカルモデル（コーディング）	qwen2.5-coder:32b
ファインチューニングの手法	LoRA/QLoRA（まずプロンプトを試してください）
LoRA ランク	通常は 16～64
トレーニングエポック数	1～3（増やすと過学習のリスクがあります）
コンテキスト圧縮	アンカー付き反復（60～80%）
圧縮のトリガー	使用率 70%、目標 50%
評価モデル	claude-haiku-5-5（コスト帯）、gpt-5.5、または gemini-3.8-flash（Google の汎用 GA モデルであり、異なるモデルを使うルールに対応する 3 社目のベンダーです。価格はここではなく models.vocab.json にあります）
品質しきい値	本番環境では 0.7、ドラフトでは 0.6
Few-shot の例	多様で代表的な例を 3～5 個
プロンプトのバージョン管理	ラベルを使った Langfuse
自動最適化	DSPy MIPROv2

関連スキル

• ork:rag-retrieval -- 埋め込みパターン、ファインチューニングより RAG が適している場合
• agent-loops -- 推論を伴う複数ステップのツール利用
• llm-evaluation -- ファインチューニング済みモデルとローカルモデルの評価
• langfuse-observability -- トレーニング実験の追跡

機能の詳細

関数呼び出し

キーワード： tool、function、tool の定義、tool schema、function schema、strict mode、並列ツール 解決する課題：

• 明確な説明と厳格なスキーマを備えたツールを定義します
• asyncio.gather を使用してツール呼び出しを並列実行します
• 入力を検証し、ツール実行ループ内のエラーを処理します

ストリーミング

キーワード： streaming、SSE、Server-Sent Events、リアルタイム、バックプレッシャー、トークンストリーム 解決する課題：

• SSE エンドポイント経由で LLM のトークンをストリーミングします
• ストリーム内のツール呼び出しを処理します
• 有界キューを使用してバックプレッシャーを管理します

ローカル推論

キーワード： Ollama、ローカル、セルフホスト可能、モデル選択、GPU、Apple Silicon 解決する課題：

• ローカル LLM 推論用に Ollama をセットアップします
• タスクとハードウェアに応じてモデルを選択します
• GPU の使用と CI 統合を最適化します

ファインチューニング

キーワード： LoRA、QLoRA、ファインチューニング、DPO、合成データ、PEFT、アライメント 解決する課題：

• パラメーター効率の高い学習向けに LoRA／QLoRA を設定します
• 合成学習データを生成して検証します
• DPO でモデルを調整し、結果を評価します