openrouter-skill

OpenRouter の統合 API を通じて、中国製／オープンソースの LLM へのインテリジェントなルーティングを可能にします。モデル選択のガイダンス、コスト最適化、および LangChain/LangGraph 統合のための本番運用パターンを提供します。

<quick_start>

1. 基本的な LangChain のセットアップ

from langchain_openai import ChatOpenAI
import os

# Any OpenRouter model works with ChatOpenAI
llm = ChatOpenAI(
    model="deepseek/deepseek-chat",
    openai_api_key=os.getenv("OPENROUTER_API_KEY"),
    openai_api_base="https://openrouter.ai/api/v1",
    default_headers={
        "HTTP-Referer": "https://your-app.com",  # Optional but recommended
        "X-Title": "Your App Name"
    }
)

response = llm.invoke("Explain quantum computing in simple terms")

2. 画像分析（チャート、ドキュメント）

from langchain_core.messages import HumanMessage
import base64

llm = ChatOpenAI(
    model="qwen/qwen-2-vl-72b-instruct",
    openai_api_key=os.getenv("OPENROUTER_API_KEY"),
    openai_api_base="https://openrouter.ai/api/v1"
)

# From URL
response = llm.invoke([
    HumanMessage(content=[
        {"type": "text", "text": "Analyze this chart and identify key trends"},
        {"type": "image_url", "image_url": {"url": "https://example.com/chart.png"}}
    ])
])

# From base64
with open("chart.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = llm.invoke([
    HumanMessage(content=[
        {"type": "text", "text": "What does this chart show?"},
        {"type": "image_url", "image_url": {"url": f"data:image/png;base64,{image_data}"}}
    ])
])

3. 自動ルーティング（OpenRouter に選択させる）

# OpenRouter's Auto model selects the best model for your prompt
llm = ChatOpenAI(
    model="openrouter/auto",  # Powered by NotDiamond
    openai_api_key=os.getenv("OPENROUTER_API_KEY"),
    openai_api_base="https://openrouter.ai/api/v1"
)

</quick_start>

<success_criteria>

• OpenRouter API キーが設定され、認証されている
• モデル選択が決定木に従っている（画像 → Qwen-VL、コード → DeepSeek Coder など）
• LangChain の ChatOpenAI 統合が、正しいベース URL とヘッダーで動作している
• 同等の品質で、欧米のモデル相当と比較して 60～97% のコスト削減
• 本番環境の信頼性のためにフォールバックチェーンが構成されている </success_criteria>

<core_concepts>

モデル選択の決定木

Task Type
│
├─ Vision/Charts ──────────> qwen/qwen-2-vl-72b-instruct ($0.40/M)
├─ Code Generation ────────> deepseek/deepseek-coder ($0.14/$0.28)
├─ Deep Reasoning ─────────> qwen/qwq-32b ($0.15/$0.40)
├─ Long Documents ─────────> moonshot/moonshot-v1-128k ($0.55/M)
├─ Fast/Cheap Tasks ───────> qwen/qwen-2.5-7b-instruct ($0.09/M)
├─ General Analysis ───────> deepseek/deepseek-chat ($0.27/$1.10)
└─ Unknown/Auto ───────────> openrouter/auto

主要な中国製 LLM

モデル	最適な用途	コスト（$/100万トークン）
deepseek/deepseek-chat	汎用的な推論、分析	入力 $0.27 / 出力 $1.10
deepseek/deepseek-coder	コード生成	$0.14 / $0.28
qwen/qwen-2-vl-72b-instruct	画像、チャート	$0.40 / $0.40
qwen/qwen-2.5-7b-instruct	高速で低コストなタスク	$0.09 / $0.09
qwen/qwq-32b	深い推論	$0.15 / $0.40
moonshot/moonshot-v1-128k	長いコンテキスト（128K）	$0.55 / $0.55

欧米モデルとのコスト比較

タスク	欧米モデル	コスト	中国製モデル	コスト	削減率
チャット	GPT-4o	$5.00/$15.00	DeepSeek Chat	$0.27/$1.10	95%
コード	Claude Sonnet	$3.00/$15.00	DeepSeek Coder	$0.14/$0.28	95%
画像	GPT-4o	$5.00/$15.00	Qwen-VL	$0.40/$0.40	97%
高速	GPT-4o-mini	$0.15/$0.60	Qwen-7B	$0.09/$0.09	60%

LangGraph マルチモデルファクトリー

from enum import Enum
from langchain_openai import ChatOpenAI
import os

class ChineseModel(str, Enum):
    DEEPSEEK_CHAT = "deepseek/deepseek-chat"
    DEEPSEEK_CODER = "deepseek/deepseek-coder"
    QWEN_VL = "qwen/qwen-2-vl-72b-instruct"
    QWEN_FAST = "qwen/qwen-2.5-7b-instruct"
    QWQ_REASONING = "qwen/qwq-32b"
    MOONSHOT_LONG = "moonshot/moonshot-v1-128k"
    AUTO = "openrouter/auto"

def create_llm(model: ChineseModel, **kwargs) -> ChatOpenAI:
    """Factory for OpenRouter LLMs with sensible defaults."""
    return ChatOpenAI(
        model=model.value,
        openai_api_key=os.getenv("OPENROUTER_API_KEY"),
        openai_api_base="https://openrouter.ai/api/v1",
        default_headers={
            "HTTP-Referer": os.getenv("APP_URL", "http://localhost"),
            "X-Title": os.getenv("APP_NAME", "LangChain App")
        },
        **kwargs
    )

# Usage
chat_llm = create_llm(ChineseModel.DEEPSEEK_CHAT)
vision_llm = create_llm(ChineseModel.QWEN_VL)
fast_llm = create_llm(ChineseModel.QWEN_FAST, temperature=0)

環境セットアップ

# .env
OPENROUTER_API_KEY=sk-or-v1-...
APP_URL=https://your-app.com      # For attribution (optional)
APP_NAME=Your App Name            # For attribution (optional)

</core_concepts>

詳細については、以下を参照してください。

• reference/models-catalog.md - 機能を含む完全なモデル一覧
• reference/routing-strategies.md - 自動、プロバイダー、カスタムルーティング
• reference/langchain-integration.md - LangChain/LangGraph パターン
• reference/cost-optimization.md - 予算管理とキャッシュ
• reference/tool-calling.md - 関数呼び出しパターン
• reference/multimodal.md - 画像、PDF、音声のサポート
• reference/observability.md - モニタリングとトレーシング

OpenRouter 統合を実装する際は、以下を確認してください。

• OPENROUTER_API_KEY 環境変数を設定する
• タスクの種類に応じて適切なモデルを選択する（決定木を参照）
• openai_api_base="https://openrouter.ai/api/v1" を指定して ChatOpenAI を使用する
• 帰属表示のために HTTP-Referer および X-Title ヘッダーを追加する
• コストへの影響を検討する（中国製モデルは 10～100 倍安価です）
• チャットインターフェースではストリーミングを有効にする
• 本番環境の信頼性のためにフォールバックチェーンを実装する
• コスト追跡／予算上限を設定する

成果サイドカーを出力する

最終ステップとして、~/.claude/skill-analytics/last-outcome-openrouter-skill.json に書き込みます：

{"ts":"[UTC ISO8601]","skill":"openrouter-skill","version":"1.0.0","variant":"default",
 "status":"[success|partial|error]","runtime_ms":[estimated ms from start],
 "metrics":{"requests_routed":[n],"models_used":[n],"total_cost_usd":[n]},
 "error":null,"session_id":"[YYYY-MM-DD]"}

一部のステージが失敗しても結果が生成された場合は、ステータスに「partial」を使用してください。出力がまったく生成されなかった場合にのみ「error」を使用してください。