-
サマリー
あらすじ・解説
関連リンク 4万行超のopenapi.yamlをTypeSpecに移行した話 この記事では、OpenAPIを使ったAPIスキーマ駆動開発で直面した課題と、それを解決するためにTypeSpecに移行した経験が紹介されています。 筆者のチームでは、APIの仕様を定義するのにOpenAPIのopenapi.yamlファイルを使っていました。開発を進めるにつれてこのファイルが4万行を超えるほど巨大になり、いくつかの問題が発生しました。最も大きな課題は、ファイルが大きすぎて手作業での編集が非常に大変になったこと、そしてGitHub CopilotやCursorのようなAI Agentを使う際に、ファイル全体を読み込ませようとすると情報量が多すぎて処理できなくなる（コンテキスト圧迫）ことでした。 そこで、これらの課題を解決するためにTypeSpecというAPI定義言語への移行を検討しました。TypeSpecはMicrosoftが開発しており、TypeScriptに似た分かりやすい文法でAPIの仕様を定義できます。TypeSpecで書いた定義から、OpenAPIやプログラムのクライアントコードなどを自動生成する「エミッター」という機能が強力です。 TypeSpecを選んだ理由はいくつかあります。まず、OpenAPIよりも構造化しやすく、ファイルを細かく分割して書けるため、巨大化しても管理しやすくなる点です。また、万が一TypeSpecが合わなかった場合でも、自動生成されたOpenAPIファイルを使えば元の運用に戻りやすい（撤退しやすい）ことも決め手になりました。さらに、記事執筆時点（2025年4月）でTypeSpecの安定版候補がリリースされ、安心して利用できるようになったことも後押ししました。 移行は、まずTypeSpecの環境をセットアップし、既存の4万行を超えるopenapi.yamlをTypeSpec形式に自動変換するツールを使いました。変換後、一部の型定義がうまく変換されないといった問題が発生しましたが、TypeSpecの定義を手作業で調整したり、変換ツールの挙動を一時的に修正したりして対応しました。最終的には、TypeSpecファイルからopenapi.yamlを自動生成し、これまで使っていたコード生成ツール（OpenAPI Generator）やテストツール（Committee）はそのまま使い続けられるようにしました。 移行後、TypeSpecファイルは元のOpenAPIファイルの半分以下（約2万行）になり、モデルやAPIルートごとにファイルを分割して管理できるようになりました。これにより、スキーマ全体の可読性が大幅に向上し、開発体験も改善されました。AI Agentも TypeSpec のファイルは小さく分割されているため、問題なく扱えるようになりました。また、TypeSpecを使えばOpenAPIのバージョンアップもエミッターの設定を変えるだけで簡単に行えるようになります。 TypeSpecへの移行は調整が必要な部分もありましたが、約2日間で完了し、大規模なAPIスキーマの管理や開発効率の向上、AI Agentとの連携といった多くのメリットが得られたとのことです。OpenAPIファイルの巨大化に悩んでいるチームにとって、TypeSpecは検討する価値のある選択肢と言えるでしょう。 引用元: https://zenn.dev/yuta_takahashi/articles/migrate-to-typespec Enhance Your AI Agent with Data Flywheels Using NVIDIA NeMo Microservices NVIDIA Technical Blog 企業でAIエージェント（自律的に動くAIシステム）を活用する際、常に変化するデータに対応し、AIの精度を維持することが大きな課題となります。これを「モデルドリフト」と呼びます。例えば、顧客対応AIが参照するデータベースの形式が変わったり、ユーザーの質問の仕方が変化したりすると、AIの回答精度が落ちてしまう可能性があります。 この課題を解決し、AIエージェントの性能を継続的に向上させるための考え方が「データフライホイール」です。これは、ユーザーからのフィードバックやシステムで収集したデータを基にAIモデルを改善し、その結果AIの性能が向上することで、より多くのユーザーに使われ、さらにデータが集まる、という好循環サイクルのことです。このサイクルを回すことで、AIは常に新しいデータに適応し、精度を高く保つことができます。 データフライホイールは、特に複雑なタスクをこなすAIエージェントにとって重要です。AIエージェントは、単一の応答だけでなく、状況を判断し、複数のツールを使ったり、情報を検索...