Ubinity
← ブログ一覧へ戻る
2026-11-21 · engineering · Ubinity

APIキーも公式サブスクも単一契約で呼ぶ:@ubinity/node-llm v2.3 の設計思想

OpenAI・DeepSeek・Qwen・Ollama・Anthropic・Geminiを単一の呼び出し契約に統合し、未対応パラメータを絶対に黙殺しない軽量Node.jsライブラリ @ubinity/node-llm のアーキテクチャ解説。

Node.js で複数のLLMプロバイダーを扱う実務では、たいてい次の2つの壁にぶつかります。

  1. 巨大な抽象化フレームワークの弊害: 依存パッケージが肥大化するうえ、OpenAI・Anthropic・Gemini・DeepSeek・Qwen・Ollama を切り替えた際、未対応パラメータ(temperature・tools・cache など)が警告なしで黙って無視され、静かなバグの原因になる。
  2. サブスクリプション活用の正規ルート問題: 個人開発や検証自動化で Claude Pro/Max・ChatGPT Plus/Pro・Antigravity の既存サブスクを活用したい場面は多いが、非公式なトークン抽出は規約違反になる。

「黙って無視しない」単一呼び出し契約(CONTRACT_VERSION)

@ubinity/node-llm(v2.3.1、MPL-2.0、Node.js >= 22)は、どのプロバイダーが応答しても「1つのリクエスト形式・1つのOpenAI互換レスポンス・1つの型付き NodeLlmError」に揃えるというシンプルな原則で設計しました。

主な設計上の割り切り

  • Optional Peer Dependencies: APIキー呼び出しに必要な公式SDK(openai / @anthropic-ai/sdk / @google/genai)だけを選択インストール。サブスク専用ならSDK不要。
  • 公式クライアント経由のサブスク実行(auth: 'subscription'): 各社公式CLI(claude、codex、agy)を空の一時ディレクトリでヘッドレス起動し、APIキー環境変数をすべて剥離してから実行します。誤って従量課金APIに請求される事故を防ぎ、WindowsからのWSL実行にも対応します。
  • 未対応オプションは即座に unsupported で失敗: サブスク呼び出しでの tools 指定や、Contract v1 で未実装の stream: true などは、黙って落とさず明示的にエラーを返します。
  • キャッシュと推論強度の正規化: cache や effort を統一表現で扱え、usage には cache_read_tokens・cache_creation_tokens・reasoning_tokens を実測値(未報告時は推測の 0 ではなく null)として返します。
const { completion } = require('@ubinity/node-llm');

const reply = await completion({
  model: 'anthropic/claude-haiku-4-5',
  auth: 'subscription',
  timeout: 120000,
  messages: [
    { role: 'system', content: '1文で簡潔に答えてください。' },
    { role: 'user', content: 'LLMルーターが未対応パラメータを黙殺してはいけない理由は?' },
  ],
});

console.log(reply.auth, reply.choices[0].message.content);

リポジトリと概要

詳細は @ubinity/node-llm 概要ページ、または GitHub リポジトリ をご覧ください。