GroqでSQL解析CLIを作る際のトークン制限対策とAPI選定基準

社内ツールにLLM（大規模言語モデル）連携を組み込みたいが、API利用料やレート制限の見積もりで止まっているエンジニアに向けて、実際に公開されているGo製CLIツール「KaizenSQL」の設計判断を題材に整理します。個人のサンドボックス開発から小規模な社内ツールまで、無料枠のLLM APIをどう選び、トークン制限とどう付き合うかは共通の悩みです。

KaizenSQLは、SQLコードを読み込んでLLMにレビューさせるGo言語製のCLIツールです。Mentor（ヒントだけ出す）、Performance（性能観点）、Security（セキュリティ観点）の3モードを切り替えて使う設計になっています。注目したいのは機能そのものより、LLM API選定とトークン制限への対処という、実運用で誰もがぶつかる部分です。

なぜGroq APIを選んだのか

開発では最初にGemini（Googleの対話型AI）でアイデア出しや設計相談を行い、実装のAPI呼び出し部分にはGroq APIを採用しています。これは「相談用のAI」と「組み込み用のAI」を分けるという、地味ですが実務で有効な使い分けです。

Groq APIは、LLMの推論を高速化する専用ハードウェア（LPU）を使ったAPIサービスです。無料枠が比較的寛容で、クレジットカード登録なしで利用開始できる点が採用理由に挙がっています。これは検証段階でコストを気にせずプロンプトのチューニングを繰り返したい場面で重要な条件です。

もう一つの決め手が、OpenAIのクライアントライブラリとの互換性です。Groq APIはOpenAI互換のインターフェースを提供しているため、Go言語用のopenaiパッケージをそのまま使い回し、接続先のベースURLとAPIキーだけ差し替えれば動作します。将来的にOpenAI本家やAzure OpenAIに切り替える際も、呼び出しロジックを書き直す必要がほぼありません。

これはAIベンダーロックインを避けるうえで実務的な判断基準になります。新規にLLM連携を組み込む際は、採用候補のAPIが「OpenAI互換」を謳っているかを最初に確認すると、将来の移行コストを抑えられます。

モード設計とプロンプトのトークン予算

KaizenSQLでは、SQLの何を分析するかを単一スキャンにせず、-m（Mentor）、-p（Performance）、-s（Security）というコマンドラインフラグでモードを明示的に選ばせています。Go言語の標準パッケージflagを使い、モードごとに異なるシステムプロンプト（AIへの役割指示）を注入する仕組みです。

この設計の背景には、採用したモデルの入力トークン上限が1分あたり8000トークンという制約があります。トークンとは、LLMがテキストを処理する際の最小単位で、日本語・英語ともに文字数とおおよそ比例する目安として使われます。SQLコードは行数が多くなりがちなため、システムプロンプトを欲張ると解析対象のコード自体を削らざるを得なくなります。

モードを分けて1回のリクエストで聞く内容を絞ることで、システムプロンプトを短く保ちつつ、トークン予算をSQLコード本体に多く割り当てる工夫をしています。1つのプロンプトで「性能もセキュリティも両方見てほしい」と欲張ると、結果的に出力の精度が落ちる、という経験則にも通じる設計です。

出力トークン上限オーバーのトラブルと対処

実装中に発生した具体的な問題が、出力トークンの上限超過エラーです。使用していたqwen/qwen3-32b系のモデルは、入力7000トークンに対して出力はわずか1000トークンという非対称な制限を持っていました。複数回実行したうち1回だけこのエラーが発生したという報告もあり、負荷や応答内容によって出力の長さが変動することがうかがえます。

対処はシンプルで、Go言語のOpenAI互換クライアントでリクエストを組む際にMaxCompletionTokensパラメータを明示的に設定する方法です。

response, err := client.CreateChatCompletion(ctx, openai.ChatCompletionRequest{
    Model: k.agentModel,
    MaxCompletionTokens: 900,
    Messages: []openai.ChatCompletionMessage{...},
})

モデルを変更するのではなく、既存モデルの出力上限に収まるようパラメータ側を調整するという判断です。モデルの個性（コード理解の精度など）を活かしつつ制約内に収める、という現実的な落としどころと言えます。

他のLLM API運用パターンとの比較

この構成は、OpenAI APIやAnthropicのClaude APIを直接使う場合と比べて何が違うのでしょうか。大きな違いは、検証コストと移行容易性のバランスです。

OpenAIやAnthropicの有料API版は精度・機能面で優位ですが、検証段階から課金が発生しやすく、学生や個人開発者が気軽に試すにはハードルがあります。一方でGroqのような無料枠の大きいOpenAI互換APIを検証用に使い、本番や精度要件が厳しい場面でOpenAI本家に切り替える、という2段階の進め方は、個人開発に限らず社内PoC（概念実証）でも応用できる考え方です。

加えて、MCP（Model Context Protocol、AIツールが外部データやツールと連携するための標準プロトコル）を使った連携を検討している場合も、まずはシンプルなAPI直接呼び出しでプロンプト設計とトークン予算の感覚をつかんでから、MCPサーバー経由の構成に移行する方が設計ミスを減らせます。いきなり複雑な連携を組むより、トークン制限とプロンプト設計の基礎を小さいCLIツールで確認する進め方は再現性があります。

今日確認できること

自分のプロジェクトでLLM連携を検討しているなら、次の点を確認してみてください。

使用候補のAPIプロバイダーが公開しているレート制限（1分あたりの入力・出力トークン数）をドキュメントで確認する
SDKやクライアントライブラリが「OpenAI互換」かどうかを確認し、将来のベンダー切り替えコストを見積もる
リクエスト時に出力トークン上限（max_tokensやMaxCompletionTokens相当のパラメータ）を明示的に指定しているか、コードを見直す
プロンプトを機能ごとに分割できないか検討し、1リクエストあたりのトークン消費を抑える設計にする

Groqの無料枠や料金体系、対応モデルの一覧は公式サイトのPricingページとモデル一覧ページで随時更新されるため、採用前に最新の制限値を確認するのが確実です。モデルごとに入出力トークンの上限が異なる点は、今回のケースのようにハマりやすい落とし穴です。

まとめ

KaizenSQLの開発過程からは、LLM連携を組み込む際の実務的な判断基準が見えてきます。

検証段階はOpenAI互換かつ無料枠の大きいAPIを使い、本番移行時のコード変更を最小化する
プロンプトとコマンドモードを分割し、トークン予算をタスクの本質部分に多く配分する
出力トークン上限は過信せず、リクエストパラメータで明示的に制御する

小さなCLIツールでの検証は、レート制限や出力上限といった「ドキュメントを読むだけでは実感しにくい制約」を体で覚える良い機会になります。手元のプロジェクトでAPIドキュメントのレート制限の項目を開き、現在のコードが上限を意識した実装になっているか、一度見直してみてください。