AIチュートリアル

jev-alignでAI機能を構築・改善する

jev-alignのインストール方法、AI分類またはスコアリングタスクの設定方法、不確かな例へのラベル付け、GEPA提案の確認、モデルプロバイダーの選択、本番データの収集と後からの最適化について学びます。

2026年9月20日約14分で読了

jev-alignとは？

jev-alignは、Sutroが提供する、TypeSafeのJevでAI Functionを構築するための実験的なコマンドラインツールです。データセットを評価し、不確実性の高い例を特定してラベル付けを依頼し、GEPAを使って改善されたFunction定義を提案します。

このツールは反復的なワークフロー向けに設計されています。ローカルデータからAI Functionを作成し、提案された変更を確認して進捗を保存できます。さらに、そのFunctionをアプリケーションで使用し、本番環境で取得した例を使って後から改善できます。

すべてのラベルはあなたが付けます。トレーニングスコアが高くても、jev-alignが提案を自動的に承認することはありません。

主な機能

不確実性に基づくラベル付け：CLIは曖昧な行を優先しつつ、ランダムな監査サンプルも含めます。
人が管理する最適化：提案された各定義を承認するか拒否するかを自分で決定できます。
複数のタスク種別：二値分類、多クラス分類、マルチラベル、順序付きスコアリングのFunctionを構築できます。
ローカルデータセットの検出：ガイド付きセットアップでCSV、Parquet、JSONLファイルを検出します。
柔軟なモデルプロバイダー：TypeSafe AI、Vercel AI Gateway、またはCloudflare Workers AIを通じてJevを実行できます。
個別のリフレクションモデル：GEPA用に、OpenAI、Anthropic、Gemini、または別のLiteLLM互換プロバイダーを設定できます。
実行内容の永続化：以前の最適化セッションを再開し、保存されたAI Functionを確認できます。
本番データの収集：アプリケーションで役立つ例を収集し、後の最適化ラウンドでラベルを付けられます。

対応しているタスク種別を理解する

開始する前に、問題に合った出力形式を選択してください。

二値分類：TrueまたはFalseを返します。
多クラス分類：固定された集合からラベルを1つだけ返します。
マルチラベル：固定された集合から0個以上のラベルを返します。
スコア：順序付きルーブリックから1つのレベルを返します。

jev-alignをインストールする

前提条件

Python 3.11以降が必要です。また、Jevプロバイダーと、対応しているリフレクションモデルプロバイダーの認証情報も必要です。

uvでインストールする

推奨されるクイックスタートでは、uvを使ってインストールします。

uv tool install jev-align

pipでインストールする

uvを使わない場合は、pipでパッケージをインストールします。

pip install jev-align

認証情報を設定する

標準のTypeSafe AI経路では、TypeSafe APIキーをエクスポートします。GEPAには、OpenAI、Anthropic、Geminiなどのリフレクションモデルプロバイダーも必要です。

export TYPESAFE_API_KEY="..."
export OPENAI_API_KEY="..."

OpenAIキーの代わりにANTHROPIC_API_KEYまたはGEMINI_API_KEYを使用できます。Vercel AI GatewayとCloudflare Workers AIは、JevプロバイダーとしてTypeSafe AIの代わりに利用できます。これらの経路ではTYPESAFE_API_KEYは必要ありません。

ガイド付きセットアップを開始する

次のいずれかのコマンドでCLIを起動します。

jeva

または：

jev-align

ガイド付きセットアップでは、ローカルのCSV、Parquet、JSONLデータセットを検出し、すぐに実行できる3つの例を表示します。プロンプトに従って、データセットの選択、タスクの定義、関連フィールドの指定、プロバイダーの設定を行ってください。

CLIのナビゲーション操作

矢印キーとEnterキーでメニューを操作します。
bを押すと、前のラベルに戻ります。
/backと入力すると、根拠の入力を終了します。
マルチラベルタスクでは、Spaceキーで選択項目を切り替えます。

フラグを使って最適化タスクを実行する

コマンドラインオプションを指定すると、ガイド付きワークフローの一部を省略できます。次の例では、投稿が航空に関するものかどうかを判定する二値Functionを構築します。

jeva optimize posts.csv \
  --question "Is the post related to aviation?" \
  --column title \
  --column text \
  --pool-size 1000

繰り返し指定した--columnオプションにより、jev-alignはtitleフィールドとtextフィールドを評価します。--pool-size 1000オプションは、作業対象のプールを1,000行に制限します。

デフォルトでは、jev-alignは最初の1,000行を使用します。データセットの行数が1,000行未満の場合は、データセット全体を使用します。すべてのフィールドを連結することも、特定の列を選択することもできます。

クラスとスコアレベルを設定する

多クラス分類およびマルチラベルタスクでは、--class "NAME=DESCRIPTION"オプションを繰り返し指定します。スコアリングタスクでは、--score-levelオプションを繰り返し指定します。利用できる正確なフラグは変更される可能性があるため、組み込みのリファレンスを確認してください。

jeva optimize --help

各最適化ラウンドの仕組み

データセットを評価する：jev-alignは設定されたデータに対して現在のFunctionを実行し、不確実性を測定します。
例を選択する：曖昧な行を選び、ランダムな監査サンプルを追加します。
ラベルを収集する：選択された例にラベルを付け、必要に応じて根拠も入力できます。
GEPAを実行する：GEPAは蓄積されたフィードバックを使って、改善された定義を提案します。
提案を確認する：CLIにスコア、確実性の変化、提案された定義の差分が表示されます。
次の操作を選択する：承認、拒否、巻き戻し、または停止して後から再開できます。

このレビュー手順は重要です。改善案は、明示的に承認するまで提案のままです。

高度な最適化設定を調整する

ガイド付きのAdvancedメニューでは、複数の設定を操作できます。

1ラウンドあたりのトレーニング用アノテーション数として、5、10、15、20のいずれかを選択します。
オプションの20%ホールドアウト評価セットを有効にします。
GEPAのメトリクス呼び出し予算を設定します。デフォルトは300です。

アノテーションラウンドを小さくすると、各レビューサイクルを短縮できます。ホールドアウトセットを使うと、最適化に使用した例とは別の評価シグナルを得られます。メトリクス呼び出し予算は、実行中にGEPAが処理できる作業量を制御します。

Jevプロバイダーを選択する

ガイド付きセットアップでは、設定済みのプロバイダーを検出し、TypeSafe AI、Vercel AI Gateway、Cloudflare Workers AIから選択できます。選択したプロバイダーはAI Functionとともに保存されるため、後続のランタイム呼び出しでも同じ経路が使用されます。

Vercel AI Gatewayを使用する

export AI_GATEWAY_API_KEY="..."
jeva optimize data.csv --question "Is this relevant?" --column text \
  --backend vercel

Cloudflare Workers AIを使用する

export CLOUDFLARE_ACCOUNT_ID="..."
export CLOUDFLARE_API_TOKEN="..."
jeva optimize data.csv --question "Is this relevant?" --column text \
  --backend cloudflare

これらの経路では、TYPESAFE_API_KEYは必要ありません。

GEPAのリフレクションモデルを設定する

GEPAのリフレクションモデルは、データセットの行を評価するJevモデルとは別のものです。OpenAI、Anthropic、Geminiのモデルは自動的に検出されます。LiteLLMプロバイダーも使用でき、Fireworks、ローカルのvLLM、その他のOpenAI互換エンドポイントに対応しています。

たとえば、ホスト型vLLMエンドポイントを設定し、そのモデルを明示的に選択します。

export HOSTED_VLLM_API_BASE="http://localhost:8000/v1"
jeva optimize data.csv --question "Is this relevant?" --column text \
  --reflection-model "hosted_vllm/Qwen/Qwen3-8B"

この分離により、ランタイムでのデータセット評価用に1つのプロバイダーを選び、GEPAの最適化処理用に別のプロバイダーを選べます。

保存済みAI Functionを管理・再開する

保存済みの関数を一覧表示するには、次を実行します。

jeva functions

特定の実行を直接再開するには、保存先ディレクトリを指定します。

jeva optimize --resume .jev-align/runs/<run-id>

再開機能は、ラベル付けを続けたい場合、保存済みの関数を見直したい場合、またはデプロイ後に取得した例を処理したい場合に便利です。

PythonでAI Functionを使用する

AIFunction.loadで保存済みの関数を読み込みます。将来のレビューに役立つ本番環境の例を関数に記録させるには、キャプチャを有効にします。

from jev_align import AIFunction

is_aviation = AIFunction.load(
    ".jev-align/runs/<run-id>",
    capture=True,
)

prediction = is_aviation(
    title="Airport expansion",
    text="A new runway opens next year.",
)

キーワード引数は、保存済みの関数が想定するフィールドに対応させる必要があります。この例では、関数がタイトルと本文を評価します。

本番データから学習を続ける

capture=Trueを指定すると、後の最適化に役立つ例をアプリケーションに保持させることができます。準備ができたらCLIに戻り、例をレビューします。

jeva functions

該当するAI Functionを選択または再開し、取得した例にラベルを付けて、GEPAに次の定義案を作成させます。同じ人によるレビュー手順が適用されます。変更を承認する前に、メトリクスと差分を確認してください。

高度なワークフローのヒント

対象を絞った列を選択する: すべてのフィールドを自動的に使用するのではなく、タスクの判断材料となるフィールドだけを含めます。
質問を具体的に書く: 明確な判断境界により、二値分類のラベルを一貫して付けやすくなります。
固定ラベルを慎重に説明する: 多クラス分類やマルチラベルタスクでは、クラスの説明を使って、重なりやすいラベルを区別します。
必要に応じて根拠を追加する: 任意の根拠を加えると、なぜ例に特定のラベルを付けるべきかについて、GEPAにより多くのコンテキストを与えられます。
監査サンプルを使用する: 曖昧な例は有用ですが、ランダムな例を使うと、不確実性に焦点を当てたサブセット以外での動作も確認できます。
スコア以外もレビューする: イテレーションを承認する前に、確信度の変化と提案された定義の差分を確認します。
再起動ではなく再開する: 保存済みの実行には蓄積したラベルが保持されるため、改善を継続できます。
プロバイダーの選択を分ける: 評価とランタイムの要件に合わせてJevバックエンドを選び、GEPA用のリフレクションモデルは独立して設定します。

まとめ

jev-alignは、Jev AI Functionを作成・改善するための人間参加型のプロセスを提供します。ローカルデータセットから始め、不確実な例にラベルを付け、GEPAが提案する定義変更をレビューして、結果を保存します。本番環境でのキャプチャを有効にし、後で同じ実行を再開することで、承認するバージョンをすべて管理しながら、実際のアプリケーション例を使って関数の改善を続けられます。