models.devを読む：AIモデル情報を提供者別データから組み立てる仕組み

models.devが解こうとしている情報の分散

models.devは、AIモデルの仕様、価格、能力を集めたオープンソースのデータベースです。プロジェクトの説明では、利用可能なAIモデル全体を参照できる単一のデータベースがなかったことが出発点になっています。ここで扱う対象はモデル名だけではありません。モデルID、入力と出力の形式、コンテキスト上限、ツール呼び出しの可否、価格などを、提供者をまたいで同じデータとして扱うための基盤です。

データはmodels.devのサイトだけに閉じていません。READMEには公開APIが示され、opencodeでも内部利用していると説明されています。つまり、このリポジトリの中心は画面そのものではなく、コミュニティが更新するデータと、それを複数の利用先へ変換する仕組みです。リポジトリの説明から確認できるライセンスはMITで、現時点の素材ではアーカイブ済みではなく、デフォルトブランチはdevです。

三つのJSONエンドポイントは用途で選ぶ

READMEが案内する入口は三つあります。api.jsonは全体のデータセットを返し、Model IDを指定した検索に使えます。このIDはAI SDKが使う識別子です。モデルを選ぶ処理で名前の表示文字列をキーにするのではなく、IDを保存する設計にすれば、同名表示や提供者の違いを切り分けやすくなります。

models.jsonは提供者に依存しないモデル情報を取り出すためのエンドポイントです。モデルそのものの能力や上限を確認したい場合はこちらの考え方が合います。catalog.jsonは提供者側のエンドポイント情報とモデル単体のメタデータを一つの応答にまとめます。提供者別の価格や接続先と、共通モデル情報を一度に処理する場面では便利ですが、どの項目がどちらの層から来たかを保持する実装が必要です。

ロゴはlogos/{provider}.svgから取得できます。providerにはanthropic、openai、googleのようなProvider IDを入れ、登録がない場合は既定のロゴが返るとREADMEにあります。ただし、認証方式、レート制限、応答サイズ、障害時の保証は文書化されていません。APIを本番の唯一の情報源にする前に、キャッシュと欠損時の表示を設計すべきです。

モデル情報と提供者情報を分離するTOML設計

リポジトリ内のデータは、提供者とモデルごとのTOMLファイルとして保存されます。models/には提供場所に左右されない事実を置き、providers/には各提供者がそのモデルをどう配信するかを置く構造です。READMEの例では、models/openai/gpt-5.tomlに基盤モデルの名前、知識範囲、能力、上限、モダリティなどを定義し、providers/openai/models/gpt-5.tomlに入力価格、出力価格、提供者側の上書きを記述します。

この分離は、同じ基盤モデルが複数のサービスから配信されるときに意味を持ちます。モデルに固有の事実と、サービス契約や提供経路によって変わる事実を同じファイルへ混ぜると、価格や上限の差分を追いにくくなります。models.devではbase_modelでモデル専用メタデータを継承し、提供者側では異なる項目だけを定義する方式が推奨されています。生成時には提供者側のフィールドがモデルメタデータより優先されるため、利用者は最終的な合成結果を確認する必要があります。

base_modelの継承で避ける重複と上書き

base_modelは、models/内の<provider>/<model-id>に対応する定義を指します。ラッパー型の提供者が既存モデルを扱う場合、description、modalities、tool_call、日付などを丸ごと複製せず、基底モデルとの差分だけを書きます。価格、推論オプション、提供者ごとのコンテキスト上限のような差分は、提供者ファイル側の責任です。

READMEには、cost、limit、modalitiesのような入れ子の表を上書きする場合、必要な値をその表に含めるというルールも示されています。配列や基本値は置き換えになり、通常のオブジェクトは深い結合として扱われるため、部分指定のつもりで既存値を失わないか確認が必要です。base_model_omitを使えば、継承後に不要なフィールドをドット区切りのパスで削除できます。

一方、古いextendsテーブルへ戻る運用はREADMEの方針と合いません。継承を追加するプルリクエストでは、基底モデルに属する項目と提供者固有の項目を一覧化し、合成後のJSONで価格、上限、能力が意図どおり残るかを確認するのが現実的です。

スキーマが表すモデルの能力と制約

スキーマはpackages/core/src/schema.tsに定義されています。提供者には表示名、AI SDKのnpmパッケージ名、認証に使う環境変数、ドキュメントURLがあり、OpenAI互換の接続先を使う場合はapiも指定できます。モデルにはattachment、reasoning、tool_call、structured_output、temperatureの対応状況、知識の基準日、公開日、更新日、重みの公開状態などが含まれます。

価格は入力、出力、推論、キャッシュ読み取り、キャッシュ書き込み、音声入出力に分かれ、制限はコンテキスト、入力、出力の上限として表されます。入力と出力のモダリティも別に持てるため、テキスト専用の処理と画像入力を許す処理を同じ表示で扱わずに済みます。statusにはalpha、beta、deprecatedを置けます。

この項目数の多さは、カタログを比較画面に使う際の注意点でもあります。READMEで示される数値や能力は、各提供者の最新契約を自動的に保証するものではありません。価格や上限を請求計算に使うなら、取得時刻と提供者の公式情報を併記し、欠損値をゼロとして処理しない仕組みが必要です。

新しい提供者を追加するときの実務

READMEの貢献手順は、まずproviders/に対象の提供者があるかを確認するところから始まります。ない場合はProvider IDのフォルダを作り、provider.tomlに名前、npmパッケージ、認証用環境変数、ドキュメントURLを記述します。OpenAI互換のエンドポイントを使う提供者では、@ai-sdk/openai-compatibleとapiの指定例が示されています。

新しい提供者にはlogo.svgも必要です。SVGは固定サイズや固定色に依存せず、塗りと線にcurrentColorを使う構造が例示されています。その後、providers側のmodels/にモデルIDをファイル名とするTOMLを置きます。IDにスラッシュがあればサブフォルダへ分けます。既存モデルを配信するだけなら、base_modelを使って同一情報の重複を抑えるのが手順に沿います。

提出物はGitHub Actionで必須フィールド、データ型、値の範囲、TOML構文を検査するとREADMEにあります。既存の提供者フィールドをモデルメタデータへ移す変更では、bun run compare:migrationsで差分を確認する案内もあります。これらはデータ品質を支える仕組みですが、Actionが通ったことだけで価格の正確さやサービスの稼働を証明するものではありません。

Bunを使う開発手順と確認できない範囲

フロントエンドをローカルで確認する手順として、READMEはBunのインストール、bun install、packages/webへの移動、bun run devを挙げています。開発用画面はhttp://localhost:3000で開きます。opencodeとの手動テストでは、依存関係を入れた後にpackages/webでbun run buildを実行し、opencode起動時のOPENCODE_MODELS_PATHをdist/_api.jsonに設定します。

この手順から、TOMLデータをWeb用のJSONへ生成し、その成果物を別のツールから参照する流れは読み取れます。ただし、素材にあるREADMEはデプロイ先、公開APIの監視、CIの全体構成、認証、レート制限を説明していません。ローカルで画面が表示されたことと、外部APIを運用できることは同じではありません。

MITライセンスは利用、変更、配布などを認める一方、ソフトウェアは現状のまま提供され、商品性や特定目的への適合性を含む保証はありません。models.devを組み込む場合は、対象モデルの収録確認、データ更新の検知、API停止時の代替、価格表示の免責を自分の責任範囲として決めてから採用するのが妥当です。

利用側でモデル選択を監査する項目

models.devの情報を自社のモデル選択画面へ組み込むときは、表示、接続、費用、能力を同じ一列の情報として扱わないことが出発点です。表示名は利用者が読むための文字列ですが、接続には提供者IDとモデルIDが必要です。費用は入力、出力、推論、キャッシュの単位を区別し、能力は添付、推論、工具呼出、構造化出力、温度指定の対応状況として扱います。項目の意味を分けて保存しないと、一覧では使えるように見えるモデルが、実際の接続処理では選べない事態が起きます。

第一に、モデルIDの所在と提供者の所在を記録します。api.jsonの全体応答から得た識別子なのか、models.jsonの共通モデル情報なのか、catalog.jsonの合成結果なのかを区別してください。第二に、価格と上限の取得日時を記録します。価格表示は利用者の予算判断に直結し、入力上限と出力上限は送信前の分割処理を左右します。値が欠落した場合にゼロ、無制限、対応可能と解釈する実装は避け、未確認として明示する方が事故を減らせます。

第三に、継承と上書きの結果を検査します。base_modelから共通能力を受け取り、提供者側で料金や制限を置く構成では、片方の変更が最終JSONへどう現れるかを確認します。statusがdeprecatedなら新規選択から外すのか、既存設定だけ許すのかも利用側で決める必要があります。open_weightsやlicenseの項目があっても、社内利用、再配布、学習利用の法的判断を自動化できるわけではありません。

最後に、READMEにない運用条件を勝手に補わないことが重要です。認証、監視、可用性、更新通知、応答時間、障害時の代替経路は素材から確認できません。これらを必要とする組織は、公式提供者の文書、契約条件、実際のAPI応答を別途確認し、models.devを参照カタログとして使う範囲を明文化してください。カタログの形式検査に合格したことと、業務システムで安全に使えることは別の判定です。

運用設計では、取得失敗と情報欠損を別の状態として扱う必要があります。取得失敗は通信、名前解決、権限、提供者側障害などの原因を持つ一時的な状態です。情報欠損は応答を受け取れたものの、価格、上限、能力、更新日などが記録されていない状態です。両者を同じ既定値へ変換すると、利用者は未確認の価格を確定値と誤認し、送信処理は未確認の上限を安全な値と誤認します。画面では未確認、取得日時、参照元を表示し、接続実行時には明示的な確認を求める設計が合います。

また、モデル版の同一性を追跡できる形で保存します。表示名、提供者名、モデルIDだけでは、同一IDの更新や提供者側の設定変更を区別できない場合があります。応答の取得時刻と元データの版、採用した価格、入力上限、出力上限を記録すれば、費用差や応答差が発生したときに調査できます。素材は更新保証や通知方法を説明していないため、この監査記録は利用者側の責任で追加する項目です。

さらに、選択履歴と実行結果を結び付けます。利用者が選んだモデルID、提供者ID、取得日時、送信時の入力上限、適用料金を一つの記録に残せば、請求額や応答失敗を追跡できます。提供者が変わった場合も、同じモデル表示名だけを見て判断せず、実際の接続先を比較できます。組織内で複数の担当者がデータを更新するなら、変更理由、参照文書、確認者を記録し、未確認情報を公開設定へ混ぜない承認手順を設けてください。素材が約束していない運用保証を、カタログ名から推測しないことがこの監査の最終基準です。

記録の保存期間、閲覧権限、削除手順も事前に定めます。価格履歴や接続履歴には利用者や業務内容が含まれる場合があるため、必要な項目だけを保存し、誰が変更を承認したかを追跡可能にします。models.devのREADMEはこの管理方法を規定していないので、組織の情報管理規程と提供者契約に合わせて設計してください。

編集部の結論

models.devは、複数のAIモデルと提供者を同じ形式で参照したい開発者や、AI SDK向けのモデルIDを自分の処理系に取り込みたいチームに向いています。一方、APIの認証、レート制限、更新保証、運用時の可用性はREADMEだけでは判断できません。採用前に必要な提供者とモデルが収録されているか、価格と制限の更新頻度、取得失敗時の扱いを実データと自分の環境で確認してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository