openrouter-skill

通过 OpenRouter 统一 API 实现对中文／开源大模型的智能路由。提供模型选择指南、成本优化方案，以及用于 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 集成正常运行，且使用正确的 base 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

主流中文大模型

模型	最适用场景	成本（美元／1M 个 token）
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 环境变量
• 根据任务类型选择合适的模型（参见决策树）
• 使用 ChatOpenAI，并设置 openai_api_base="https://openrouter.ai/api/v1"
• 添加 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"。