AI 튜토리얼

jev-align으로 AI 기능 구축 및 개선

jev-align 설치, AI 분류 또는 점수화 작업 구성, 불확실한 예시 라벨링, GEPA 제안 검토, 모델 제공업체 선택, 향후 최적화를 위한 프로덕션 데이터 수집 방법을 알아봅니다.

2026년 9월 20일약 12분 소요

jev-align이란?

jev-align은 Sutro에서 제공하는 실험적인 명령줄 도구로, TypeSafe의 Jev를 사용해 AI 함수를 구축합니다. 데이터 세트를 평가하고, 불확실한 예제를 식별한 다음, 사용자에게 해당 예제의 라벨 지정을 요청하고, GEPA를 사용해 개선된 함수 정의를 제안합니다.

이 도구는 반복적인 워크플로에 맞게 설계되었습니다. 로컬 데이터에서 AI 함수를 만들고, 제안된 변경 사항을 검토하고, 진행 상황을 저장하고, 애플리케이션에서 함수를 사용한 후, 운영 환경에서 수집한 예제로 나중에 함수를 개선할 수 있습니다.

모든 라벨은 사용자가 지정합니다. 학습 점수가 높아져도 jev-align이 제안을 자동으로 수락하지는 않습니다.

주요 기능

불확실성 기반 라벨 지정: CLI는 모호한 행을 우선 처리하면서 무작위 감사 샘플도 포함합니다.
사람이 제어하는 최적화: 제안된 각 정의를 수락할지 거부할지 사용자가 결정합니다.
다양한 작업 유형: 이진, 다중 클래스, 다중 라벨 또는 순서형 점수 함수를 구축할 수 있습니다.
로컬 데이터 세트 검색: 안내형 설정이 CSV, Parquet 및 JSONL 파일을 찾습니다.
유연한 모델 제공자: TypeSafe AI, Vercel AI Gateway 또는 Cloudflare Workers AI를 통해 Jev를 실행할 수 있습니다.
분리된 반영 모델: GEPA에 사용할 OpenAI, Anthropic, Gemini 또는 다른 LiteLLM 호환 제공자를 구성할 수 있습니다.
실행 상태 저장: 이전 최적화 세션을 재개하고 저장된 AI 함수를 확인할 수 있습니다.
운영 환경 수집: 유용한 애플리케이션 예제를 수집하고 이후 최적화 라운드에서 라벨을 지정할 수 있습니다.

지원되는 작업 유형 이해하기

시작하기 전에 문제에 맞는 출력 형식을 선택하세요.

이진: True 또는 False를 반환합니다.
다중 클래스: 고정된 집합에서 정확히 하나의 라벨을 반환합니다.
다중 라벨: 고정된 집합에서 0개 이상의 라벨을 반환합니다.
점수: 순서가 있는 평가 기준에서 하나의 수준을 반환합니다.

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 데이터 세트를 검색하고 바로 실행할 수 있는 세 가지 예제를 제공합니다. 프롬프트에 따라 데이터 세트를 선택하고, 작업을 정의하고, 관련 필드를 선택하고, 제공자를 구성하세요.

CLI 탐색 조작

화살표 키와 Enter 키로 메뉴를 탐색합니다.
이전 라벨로 돌아가려면 b를 누릅니다.
이유 입력 프롬프트를 종료하려면 /back을 입력합니다.
다중 라벨 작업에서 선택 항목을 전환하려면 Space 키를 누릅니다.

플래그를 사용해 최적화 작업 실행

명령줄 옵션을 제공하면 안내형 워크플로의 일부 단계를 건너뛸 수 있습니다. 다음 예제는 게시물이 항공과 관련이 있는지 판단하는 이진 함수를 구축합니다.

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은 구성된 데이터에 현재 함수를 실행하고 불확실성을 측정합니다.
예제 선택: 모호한 행을 선택하고 무작위 감사 샘플을 추가합니다.
라벨 수집: 선택된 예제에 라벨을 지정하고 선택적으로 이유를 제공할 수 있습니다.
GEPA 실행: GEPA는 축적된 피드백을 사용해 개선된 정의를 제안합니다.
제안 검토: CLI는 점수, 확실성 변화 및 제안된 정의의 차이를 표시합니다.
다음 작업 선택: 수락, 거부, 되돌리기를 선택하거나 중지한 후 나중에 재개할 수 있습니다.

이 검토 단계는 중요합니다. 개선 사항은 사용자가 명시적으로 수락할 때까지 제안으로 남습니다.

고급 최적화 설정 조정

가이드의 Advanced 메뉴에서는 여러 설정을 조정할 수 있습니다.

라운드당 5개, 10개, 15개 또는 20개의 학습 주석을 선택합니다.
선택적으로 20%의 보류 평가 세트를 활성화합니다.
GEPA의 메트릭 호출 예산을 설정합니다. 기본값은 300입니다.

주석 라운드 수를 줄이면 각 검토 주기를 더 빠르게 진행할 수 있습니다. 보류 세트는 최적화에 사용된 예시와 별도의 평가 신호를 제공할 수 있습니다. 메트릭 호출 예산은 실행 중 GEPA가 수행할 수 있는 작업량을 제어합니다.

Jev provider 선택

가이드 설정은 구성된 provider를 감지하고 TypeSafe AI, Vercel AI Gateway, Cloudflare Workers AI 중에서 선택할 수 있도록 합니다. 선택한 provider는 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 provider를 사용하면 Fireworks, 로컬 vLLM 및 기타 OpenAI 호환 엔드포인트를 포함한 모든 provider도 사용할 수 있습니다.

예를 들어 호스팅된 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"

이렇게 분리하면 런타임 데이터 세트 평가에는 한 provider를 사용하고 GEPA의 최적화 작업에는 다른 provider를 선택할 수 있습니다.

저장된 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가 다음 정의를 제안하도록 합니다. 동일한 사람 검토 프로세스가 적용됩니다. 변경 사항을 수락하기 전에 메트릭과 diff를 확인합니다.

고급 워크플로 팁

집중할 열을 선택하세요: 모든 필드를 자동으로 사용하기보다 작업에 대한 근거를 제공하는 필드만 포함합니다.
정확한 질문을 작성하세요: 명확한 결정 경계가 있으면 이진 분류 라벨을 일관되게 지정하기가 더 쉽습니다.
고정 라벨을 신중하게 설명하세요: 다중 클래스 및 다중 라벨 작업에서는 클래스 설명을 사용해 그렇지 않으면 겹칠 수 있는 라벨을 구분합니다.
필요하면 근거를 추가하세요: 선택적 근거는 예시에 특정 라벨을 지정해야 하는 이유에 대해 GEPA에 더 많은 맥락을 제공할 수 있습니다.
감사 샘플을 사용하세요: 모호한 예시는 유용하지만, 무작위 예시를 통해 불확실성에 초점을 둔 하위 집합 외부의 동작도 확인할 수 있습니다.
점수 이상을 검토하세요: 반복 작업을 수락하기 전에 확실성 변화와 제안된 정의 diff를 확인합니다.
다시 시작하지 말고 재개하세요: 저장된 실행은 누적된 라벨을 보존하므로 지속적인 개선이 가능합니다.
provider 선택을 분리하세요: 평가 및 런타임 요구 사항에는 Jev 백엔드를 선택하고, GEPA에는 반영 모델을 별도로 구성합니다.

결론

jev-align은 Jev AI Function을 만들고 개선하기 위한 사람 참여형 프로세스를 제공합니다. 로컬 데이터 세트로 시작하고, 불확실한 예시에 라벨을 지정하고, GEPA가 제안한 정의 변경 사항을 검토한 다음 결과를 저장합니다. 운영 캡처를 활성화하고 나중에 동일한 실행을 재개하면 실제 애플리케이션 예시를 활용해 함수를 계속 개선하면서도 수락한 각 버전을 직접 관리할 수 있습니다.