JSON Schema抽出に向けてClineをOpenAI互換プロバイダーに接続する

Clineは、OpenAI互換エンドポイントを提供するプロバイダーであれば、公式のOpenAI API以外も利用できます。構造化データ抽出のプロジェクトでは、Clineをパイプラインの構築を支援するコーディングエージェントとして捉え、モデルがスキーマに準拠したJSONを返す保証と混同しないことが大切です。プロバイダーの公式情報に記載された内容で接続を設定し、抽出結果は必ずアプリケーションのコードで検証してください。

構造化データ抽出に適した設定の考え方

OpenAI互換APIはインターフェースの仕様を示すものであり、すべてのプロバイダーが同じモデル、ツール呼び出し、構造化出力機能を実装していることを保証するものではありません。ClineのOpenAI互換プロバイダーガイドでは、プロバイダーごとのBase URL、APIキー、モデルIDを設定するよう案内しています。また、コンテキストウィンドウ、最大出力トークン数、画像対応、コンピューター操作などのモデル設定についても説明されています。

このガイドには、ClineでJSON Schema検証を行う機能の説明はありません。そのため、役割を分けて考えましょう。Clineは抽出ワークフローの開発やレビューに使い、モデルの出力はアプリケーション側でパースして検証します。こうすることで、不正なJSONやスキーマ違反を黙って受け入れるのではなく、明示的なエラーとして扱えます。

前提条件

Clineの設定を開く前に、利用するプロバイダーから次の情報を確認してください。

• 必要なパスを含む、正確なAPI Base URL。
• APIキー、または公式に案内されている別の認証方法。
• そのエンドポイントで利用できる正確なモデルID。
• 利用予定のモデルがツール呼び出しや関数呼び出しに対応しているか、また使用する構造化出力やレスポンス形式のオプションがあるかを記載したドキュメント。

抽出の要件も定義しておきましょう。必要なフィールドとその型、無効と判断する条件、情報が欠落または曖昧な場合の処理を決めておきます。スキーマで形や制約は検証できますが、抽出した値が事実として正しいことまでは確認できません。

Clineでプロバイダーを設定する

1. 歯車アイコンからClineの設定を開き、API ProviderでOpenAI Compatibleを選択します。
2. プロバイダー指定の正確なBase URLを入力します。Clineのガイドでも、Base URLはプロバイダーごとに異なると説明されています。公式のOpenAI APIを設定する場合を除き、公式OpenAIのエンドポイントを代わりに入力しないでください。
3. プロバイダーから発行されたAPI Keyと、正確なModel IDを入力します。API形式に互換性があっても、モデル名はプロバイダー間で使い回せません。
4. モデルの設定項目を確認します。コンテキストウィンドウと最大出力の値は、モデルが対応する範囲に設定してください。コンピューター操作や画像対応は、プロバイダーとモデルが対応を明記している場合にのみ有効にします。
5. 選択したプロバイダーの接続確認機能がClineにある場合は実行してください。ない場合は、リスクの低い小さなタスクを試し、プロバイダーの応答とClineのエラー詳細を確認します。

OneMux経由で接続する場合は、入力するエンドポイント、認証情報、モデルの詳細を、最新のOneMuxクイックスタートとAPIドキュメントで確認してください。OneMuxは、単一のOpenAI互換APIを通じて主要なAIモデルを利用できるサービスで、モデルへのアクセス、ルーティング、キー、利用額の可視化を提供します。ただし、これはOneMuxとClineの連携がテスト済みであるという意味ではありません。Clineが必要とするリクエスト機能を、公式に案内されたエンドポイントと選択したモデルがサポートする場合に限り接続してください。OneMuxモデル一覧で利用可能なモデルを確認できますが、正確なモデルIDと機能は最新のプロバイダードキュメントで確認してください。

Clineに抽出ワークフローの構築を依頼する

スキーマと実装要件を、コーディングタスクの一部としてClineに伝えます。たとえば、次のように指示できます。

Implement invoice extraction for our application using the JSON Schema in the project. Do not guess missing values. Parse the model response and validate it locally against the schema before returning data. Add tests for valid JSON, malformed JSON, missing required fields, and values that violate constraints. Do not assume the provider supports a particular structured-output parameter; use only features documented for the configured endpoint and model.

この指示はClineに検証レイヤーを作成させるものであり、プロバイダーの特別な機能を有効にするものではありません。以下は、Ajvを使ってローカルで検証するTypeScriptの例です。フィールドや制約は、独自の抽出要件に合わせて調整してください。

import Ajv from "ajv";

const schema = {
  type: "object",
  additionalProperties: false,
  required: ["invoice_number", "total", "currency"],
  properties: {
    invoice_number: { type: "string", minLength: 1 },
    total: { type: "number", minimum: 0 },
    currency: { type: "string", pattern: "^[A-Z]{3}$" }
  }
};

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(schema);

export function validateInvoice(candidate: string) {
  let value: unknown;

  try {
    value = JSON.parse(candidate);
  } catch {
    return { ok: false as const, errors: ["Invalid JSON"] };
  }

  if (!validate(value)) {
    return { ok: false as const, errors: validate.errors ?? [] };
  }

  return { ok: true as const, value };
}

ここでは、additionalProperties: falseで想定外のフィールドを拒否し、requiredと各プロパティの制約で受け入れるデータの形を定義しています。スキーマ検証に成功したということは、その値が定義したルールを満たしたという意味であり、請求書を正しく読み取れたことを意味するわけではありません。必要に応じて、合計金額の照合や通貨が許可リストに含まれているかの確認など、業務固有のチェックを追加してください。

正常系だけでなく境界条件もテストする

少なくとも次の4ケースのテストをClineに作成させましょう。正常な抽出、不正なJSON、必須プロパティの欠落、型または形式が誤った値です。さらに、情報が曖昧または存在しない場合のテストも追加し、アプリケーションで拒否するのか、要確認として返すのか、nullを許可するスキーマを使うのかを決めてください。

モデルの出力は、パースと検証が終わるまで信頼できないものとして扱います。検証に失敗したら、わかりやすいエラーを返すか、レコードをレビューに回してください。検証エラーをフィードバックとして再試行する方法もありますが、再試行しても正しさが保証されるわけではありません。プロバイダーがスキーマ制約付きのネイティブ出力に対応していると明記している場合は、追加の保護策として利用できる可能性があります。そのオプションを追加する前に、対象のエンドポイントとモデルが対応していることを確認してください。

制限事項とトラブルシューティング

• APIキーが無効: 選択したプロバイダーのキーか、正しくコピーされているか確認してください。シークレットをプロンプトや公開ログに貼り付けないでください。
• モデルが見つからない: モデルIDとBase URLの組み合わせを再確認してください。Clineのガイドによると、利用可能なモデルIDはプロバイダーによって異なります。
• 接続エラー: エンドポイントが正確で、利用環境から到達できることを確認してください。ネットワークやファイアウォールの制限も確認します。
• 出力が有効なJSONではない: Clineの設定ガイドは、プロバイダーがスキーマ制約付き出力に対応していることを示すものではありません。ローカルでのパースと検証を続け、レスポンス形式の機能についてはプロバイダーのドキュメントで確認してください。
• Clineのエージェント操作が失敗する: ガイドでは、ツール呼び出しや関数呼び出しに対応するモデルも含め、コンピューター操作をモデル設定の機能として挙げています。ただし、互換性のあるプロバイダーすべてがこれらの呼び出しに対応するとは保証されていません。エージェント操作に依存する前に、選択したエンドポイントとモデルの対応状況を公式情報で確認してください。

別のプロバイダーを使う場合も、同じ手順に従います。Clineのプロバイダー設定手順で入力する設定を確認し、モデルIDと機能の制限はプロバイダーのドキュメントで確認してください。アクセス方法を比較する際は、OneMuxの料金も確認できます。このチュートリアルでは、料金や節約効果については述べていません。

まとめ

プロバイダーの公式情報に記載されたBase URL、APIキー、モデルIDを使ってClineを設定します。構造化データ抽出では、パイプラインの実装にClineを活用しつつ、パースした出力をアプリケーションコード内で独自のJSON Schemaに照らして検証してください。OpenAI互換であることは便利な出発点ですが、すべてのエンドポイントがスキーマ検証やコーディングエージェントのツール呼び出しに対応する証拠にはなりません。

参考情報

• Cline: OpenAI Compatibleプロバイダーの設定 — プロバイダー設定、モデル設定、トラブルシューティング。