LAPIS: 知的システム向け軽量 API 仕様（Lightweight API Specification for Intelligent Systems）の技術的概要

本論文は、大規模言語モデル（LLM）が API 仕様を消費する際の文脈ウィンドウ効率を劇的に向上させるための新しいドメイン固有フォーマット「LAPIS」を提案するものです。OpenAPI 仕様がドキュメント生成やコード生成向けに設計されているため、LLM にとっては過剰なトークンコストを生んでいるという問題意識に基づいています。

以下に、問題定義、手法、主要な貢献、評価結果、および意義について詳細をまとめます。

1. 問題定義 (Problem)

LLM を活用したコード生成、自律エージェント、API 支援推論において、API 仕様はモデルの「真実の源泉（Source of Truth）」として頻繁にコンテキストに組み込まれます。しかし、現在の事実上の標準であるOpenAPI Specificationには、LLM 消費パターンとの間に以下の重大なミスマッチが存在します。

• 構造的オーバーヘッド: JSON Schema のネストされた型定義（type, properties, required など）は、人間が一行で表現できる内容を膨大なトークン数で記述させています。
• エラー定義の重複: OpenAPI では各操作（エンドポイント）ごとにエラーレスポンスを定義する必要があります。例えば、GitHub API 仕様では 1,080 の操作に対して 1,594 回もエラー定義が重複しており、404 Not Found だけで 531 回出現しています。
• 無関係なメタデータ: 連絡先情報、ライセンス、外部ドキュメントへのリンク、タグ定義、拡張機能（x-*）など、LLM の推論には不要な情報が大量に含まれています。
• 欠落する運用コンテキスト: レート制限、ウェブフックのトリガー条件、操作のシーケンスなど、LLM が API 使用を推論するために必要な情報は、OpenAPI には存在しないか、自由テキストとして埋もれています。

これらの要因により、LLM のコンテキストウィンドウが浪費され、コスト増大と推論能力の低下を招いています。

2. 手法と設計原則 (Methodology & Design Principles)

LAPIS は、OpenAPI の代替ではなく、LLM 向けに変換するターゲットフォーマットとして設計されました。その設計は以下の 5 つの原則に基づいています。

1. トークンの最小化: 構文要素のすべてがトークンコストを正当化する必要があり、OpenAPI YAML 比で 70-80% の削減を目標とします。
2. LLM ネイティブな構文: 深くネストした JSON/YAML ではなく、人間がホワイトボードに描くような「関数シグネチャ」やインデントベースのグループ化、自然言語に近い構文を採用します。
3. OpenAPI からの損失のない変換: 決定論的なルールに基づき、OpenAPI 3.x から LAPIS への自動変換を可能にします。
4. 人間による可読性: 開発者がドキュメントなしで理解できる自己記述的な形式です。
5. 推論のための意味的完全性: コード生成に必要な詳細な検証キーワードは除外しますが、LLM の推論に必要な情報はすべて保持します。

LAPIS の主要な構造的革新:

• 中央集権的なエラー定義: [errors] セクションでエラーを一度だけ定義し、操作ごとに参照させることで重複を排除します。
• ウェブフックのトリガー条件: ! プレフィックスを用いて、イベント発火の语义的条件（例：invoice.status が "paid" に変更されたとき）を構造的に記述します。
• 構造化されたレート制限: [limits] セクションで、プランごとのレート、クォータ、超過時の挙動を構造化して記述します。
• 操作フローの宣言: [flows] セクションで、複数ステップの操作シーケンス、分岐、待機状態を明示的に定義します。

3. 主要な貢献 (Key Contributions)

1. LAPIS 仕様の正式化: 構文、EBNF による文法、型システムを含む v0.1.0 の仕様を定義しました。
2. 決定論的変換ルールの確立: OpenAPI 3.x から LAPIS への変換アルゴリズム（参照解決、スキーマの平坦化、エラーの集約など）を提案し、Python パッケージおよびブラウザツールとして実装しました。
3. 実証的評価: 5 つの実世界 API 仕様（GitHub, Twilio, DigitalOcean など）を用いたベンチマークにより、トークン削減効果を定量化しました。
4. 構造的無駄の分析: 実世界の OpenAPI 仕様におけるエラー定義の重複やメタデータの過剰さを分析し、その非効率性を明らかにしました。

4. 評価結果 (Results)

5 つの API 仕様（エンドポイント数 19〜1,080）を対象に、cl100k_base トークナイザーを用いて評価を行いました。

• トークン削減率:
  • OpenAPI YAML 対 LAPIS: 平均 85.5% の削減（最大 92.1%）。
  • OpenAPI JSON 対 LAPIS: 平均 88.6% の削減。
  • 例：GitHub API（1,080 エンドポイント）は、OpenAPI YAML の 1,811,843 トークンから LAPIS の 313,101 トークンへ削減され、82.7% の削減を達成しました。
• 削減の要因:
  • メタデータの排除（25-30%）
  • ネスト構造からシグネチャ構文への移行（25%）
  • 型システムの圧縮（15%）
  • エラーの中央集権化（10-20%、大規模 API では支配的な要因）
• スケーラビリティ: API の複雑さ（特に型定義の数）が増すほど削減率は高くなる傾向があります。
• トークナイザーの安定性: cl100k_base と o200k_base の間で結果の差は 2% 未満であり、削減効果はエンコーディング依存ではないことが確認されました。

5. 意義とコストへの影響 (Significance)

LAPIS は単なる圧縮フォーマットではなく、LLM の推論能力を向上させるための「情報密度の高い」フォーマットです。

• コスト削減: トークン削減は直接的な金銭的節約につながります。GitHub API 仕様をコンテキストに含める場合、1,000 回の LLM 呼び出しあたり、OpenAPI YAML 使用時と比較して約 4,497 ドル（約 54 万円） のコスト削減が可能と試算されています。
• 情報量の増加: LAPIS は OpenAPI から不要な情報を削除するだけでなく、ウェブフックの条件やレート制限の構造、操作フローなど、OpenAPI には存在しなかった「運用上の意味」を構造化して追加しています。これにより、LLM はより高度な推論（例：レート制限を考慮したリトライ戦略の立案、複雑な API 操作の計画）が可能になります。
• エコシステムへの適合性: MCP（Model Context Protocol）などの実行レイヤーと補完関係にあり、LAPIS が「理解のための仕様」、MCP が「実行のためのプロトコル」として機能します。

結論

LAPIS は、OpenAPI が抱える構造的な非効率性を解決し、LLM 向けに最適化された API 記述フォーマットとして確立されました。実証データは、LLM のコンテキストウィンドウを劇的に節約しつつ、推論に必要な情報を維持・強化できることを示しています。このフォーマットはオープンソース（CC BY 4.0）として公開されており、変換ツールや VS Code 拡張機能も提供されています。今後の課題として、LLM のタスク精度向上を実証する実験や、双方向変換の研究が予定されています。