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つの壁にぶつかります。
- 巨大な抽象化フレームワークの弊害: 依存パッケージが肥大化するうえ、OpenAI・Anthropic・Gemini・DeepSeek・Qwen・Ollama を切り替えた際、未対応パラメータ(
temperature・tools・cacheなど)が警告なしで黙って無視され、静かなバグの原因になる。 - サブスクリプション活用の正規ルート問題: 個人開発や検証自動化で 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 リポジトリ をご覧ください。