Files
lolympus-agent/docs/service-evaluation-operations.md
T

14 KiB
Raw Blame History

lolympus-agent Service and Evaluation Operations

이 문서는 lolympus-agent의 운영 흐름과 evaluation 파이프라인을 한 곳에서 보기 위한 runbook이다. 실시간 응답 경로, background worker, shadow evaluation, human review, calibration, closed-loop prompt experiment까지 포함한다.

1. 프로세스 구성

운영 프로세스는 크게 두 개다.

프로세스 엔트리포인트 역할
agent src/main.ts NATS request/reply를 받아 실시간 온보딩 응답 생성
worker src/workers/background.ts Redis Stream background job 처리, shadow eval, archive, drift, review routing

PM2 기준으로는 ecosystem.config.cjs에서 agent와 worker를 함께 띄운다.

npm run pm2:dev
npm run pm2:test
npm run pm2:prod

개발 환경 단독 실행은 기존 스크립트를 사용한다.

npm run start:dev

2. Bootstrap 흐름

src/main.ts의 기동 순서는 다음과 같다.

  1. loadEnvironmentFromNodeEnv()로 env-vars/{NODE_ENV}.env 로드
  2. logger/tracing 초기화
  3. NATS 연결
  4. Garnet/Redis 연결
  5. LLM endpoint와 provider key 구성
  6. MongoDB 연결, 가능하면 room context 활성화
  7. Agent 생성
  8. OnboardingSkill 등록
  9. lolympus-agent.request 구독 시작

중요한 점은 NATS가 가장 먼저 외부 TLS 연결을 시도한다는 것이다. 따라서 bootstrap fatal error가 certificate has expired이고 ✓ NATS connected 로그가 없었다면 1순위 원인은 NATS_ENDPOINT 인증서 만료다.

3. 실시간 응답 흐름

본체는 NATS request/reply로 agent에 요청한다.

lolympus-agent.request
  -> Agent.handleRequest
  -> OnboardingSkill.handle
  -> AgentResponse

OnboardingSkill.handle() 내부 흐름:

  1. Garnet에서 온보딩 세션 로드
  2. user message와 trigger 기반 intent classify
  3. session, trigger, intent로 DerivedState 생성
  4. shouldRespond=false면 empty response 반환
  5. responseMode=template이면 template fallback 응답
  6. LLM 경로면 prompt build 후 orchestrator 실행
  7. tier에 따라 planner/responder/critic/tool-loop 사용
  8. validator로 응답 검증
  9. 최종 응답 반환
  10. blackboard 업데이트
  11. shadow eval event를 background stream에 비동기 발행

실시간 사용자 응답은 9번에서 끝난다. Evaluation은 11번 이후 worker가 비동기로 처리한다.

4. Prompt와 Tool 경로

Prompt는 src/skills/onboarding/prompts/builder.ts가 만든다.

기본 layer:

  • persona
  • policy
  • state
  • examples
  • context

PROMPT_VARIANT_ID가 설정되면 src/eval/proposals/{variantId}.json manifest를 읽어 prompt layer diff를 적용한다. 운영 반영은 env로 variant를 선택하는 방식이며, proposal 생성과 tournament는 별도 CLI에서 수행한다.

Tool loop는 responseMode=llm-with-tools일 때 작동한다. Built-in tool은 src/tools/builtins/*에 있다.

5. Background Worker 흐름

Worker는 lolympus-agent:background Redis Stream을 consumer group bg-worker로 읽는다.

Job type 처리
shadow-eval 실시간 응답을 rule/LLM/process 기준으로 평가
summarize 오래된 대화 일부를 요약해 summary slot에 저장

Worker는 pending job을 복구하고, delivery count가 한도를 넘으면 DLQ로 이동한다.

Stream 용도
lolympus-agent:background background job queue
lolympus-agent:background:dlq 반복 실패 job 저장

6. Shadow Evaluation 흐름

실시간 응답이 만들어지면 ShadowEvalBus가 background stream에 shadow-eval job을 발행한다.

Worker는 이 job을 받아 다음을 수행한다.

  1. validator 재실행
  2. LLM judge 실행
  3. process trace가 있으면 process judge 실행
  4. latency, tier, intent, phase, judge 결과 저장

결과는 Redis Stream에 저장된다.

lolympus-agent:eval:results

이 Stream이 이후 evaluation 운영의 원천 데이터다.

7. 주기 Evaluation 작업

Worker는 일정 간격으로 eval result를 가공한다.

작업 기본 주기 결과
aggregation EVAL_AGG_TICK_MS 5분 slice별 Redis Hash metric
archive EVAL_ARCHIVE_TICK_MS 1시간 MongoDB eval_archive
drift detection EVAL_DRIFT_TICK_MS 24시간 eval-drift alert
promotion EVAL_PROMOTE_TICK_MS 24시간 golden candidate jsonl
review routing EVAL_REVIEW_TICK_MS 5분 human review queue
review label archive archive tick과 함께 MongoDB eval_review_labels

Slice 정의:

tier × intent × phase

예:

0:photo-question:photo-pending
1:discord-question:step1-completed

8. Redis Key Schema

주요 Redis/Garnet key:

Key Type 용도
lolympus-agent:background Stream worker job queue
lolympus-agent:background:dlq Stream worker dead-letter queue
lolympus-agent:eval:results Stream shadow eval 결과
lolympus-agent:eval:baseline String 최근 안정 baseline report
lolympus-agent:eval:agg:{tier}:{intent}:{phase} Hash slice별 count/score/latency/process metric
lolympus-agent:eval:agg:cursor String aggregation cursor
lolympus-agent:eval:archive:cursor String eval archive cursor
lolympus-agent:eval:review:queue Stream human review 대기 큐
lolympus-agent:eval:review:labeled Stream human review label
lolympus-agent:eval:review:cursor String review routing cursor
lolympus-agent:eval:review:dedupe:{evalStreamId} String 동일 eval result 중복 라우팅 방지
lolympus-agent:eval:review:label-archive:cursor String review label archive cursor
lolympus-agent:alert:dedupe:{kind} String alert rate limit

9. MongoDB Collections

Collection 생성/사용 모듈 용도
eval_archive src/eval/archive.ts shadow eval 결과 장기 보관
eval_review_labels src/eval/review/label-archive.ts 사람 라벨 장기 보관
eval_tournaments src/eval/loop/tournament.ts prompt variant tournament 결과

eval_archive는 evaluatedAt 기준 TTL index를 가진다. 기본 보관 기간은 EVAL_ARCHIVE_TTL_DAYS=30이다.

10. Human Review 흐름

Review routing은 eval result 중 사람이 봐야 할 케이스를 큐에 넣는다.

조건:

  • LLM judge overall이 낮음
  • validator와 LLM judge가 불일치
  • validator soft-warn
  • rare slice

큐:

lolympus-agent:eval:review:queue

라벨링:

npm run eval:review -- --limit=20

특정 reason만 보기:

npm run eval:review -- --reason=low-score --limit=10

stale pending item을 다시 큐에 넣기:

npm run eval:review -- --reset-pending

세션 라벨을 JSONL로 저장:

npm run eval:review -- --limit=20 --export-labeled=eval-reports/review-labels.jsonl

라벨 결과는 lolympus-agent:eval:review:labeled Stream에 쌓이고 archive tick에서 eval_review_labels로 영속화된다.

11. Calibration 흐름

Calibration은 사람 점수와 LLM judge 점수의 상관을 계산한다.

npm run eval:calibrate

CI나 수동 gate로 쓰려면:

npm run eval:calibrate -- --check

pairs < 10이면 표본이 부족하므로 경고만 출력하고 실패 처리하지 않는다. 충분한 라벨이 쌓이면 EVAL_CALIBRATION_MIN_CORR 기준으로 LLM judge 신뢰도를 감시한다.

12. Report와 Promotion

Slice별 약한 영역 확인:

npm run eval:report -- --worst=20

최근 7일 대신 다른 window:

npm run eval:report -- --worst=20 --since=24h
npm run eval:report -- --top=20 --since=30d

Golden candidate 확인:

npm run eval:promote -- --dry-run

Candidate 파일에 추가:

npm run eval:promote

기본 출력:

src/eval/golden/onboarding.candidate.jsonl

Promotion 우선순위:

  1. human-labeled fail
  2. low-score
  3. rule/LLM disagree
  4. rare-slice

candidate는 바로 golden으로 승격되는 것이 아니라 사람이 직접 검토해 onboarding.jsonl로 옮긴다.

13. Closed Loop 흐름

Phase 9의 closed loop는 prompt/tool 개선안을 만들고 tournament로 비교하는 흐름이다.

13.1 Proposal 생성

약한 slice를 지정한다.

npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending

archive case 수가 부족해도 강제로 실행하려면:

npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending --force

결과는 git-tracked proposal manifest로 저장된다.

src/eval/proposals/{variantId}.json

13.2 Tournament 실행

Control과 variant를 비교한다.

npm run eval:tournament -- --variants=control,<variantId>

특정 archive case만 지정:

npm run eval:tournament -- --variants=control,<variantId> --case-ids=1-0,2-0

결과 조회:

npm run eval:tournament-results
npm run eval:tournament-results -- --variant=<variantId>

Tournament는 A/B 위치 편향을 줄이기 위해 variant 순서를 바꾼 match도 실행하고 ELO를 갱신한다. 결과는 MongoDB eval_tournaments에 저장된다.

13.3 운영 반영

운영 prompt에 variant를 반영하려면 env를 설정한다.

PROMPT_VARIANT_ID=<variantId>

반영 전에는 반드시 다음을 확인한다.

npm run typecheck
npm run lint
npm run build
npm test
npm run eval -- --skip-llm-judge --no-publish-report

Variant 적용은 자동 머지가 아니다. 사람이 tournament 결과와 sample match를 보고 결정한다.

14. Eval CLI 요약

명령 용도
npm run eval golden set 실행
npm run eval:capture MongoDB events에서 golden scaffold 추출
npm run eval:baseline 안정 baseline 저장
npm run eval:report archive slice report 출력
npm run eval:promote golden candidate 추출
npm run eval:review human review CLI
npm run eval:calibrate 사람/LLM judge calibration
npm run eval:propose prompt/tool improvement proposal 생성
npm run eval:tournament prompt variant A/B tournament 실행
npm run eval:tournament-results tournament 결과 조회

15. 주요 Env

Env 기본값 용도
EVAL_STREAM_MAXLEN 10000 eval results Stream maxlen
EVAL_AGG_TICK_MS 300000 aggregation tick
EVAL_AGG_TTL_SEC 604800 slice metric TTL
EVAL_ARCHIVE_TICK_MS 3600000 archive tick
EVAL_ARCHIVE_TTL_DAYS 30 archive TTL days
EVAL_DRIFT_TICK_MS 86400000 drift tick
EVAL_PROMOTE_TICK_MS 86400000 promotion tick
EVAL_REVIEW_TICK_MS 300000 review routing tick
EVAL_REVIEW_QUEUE_MAXLEN 500 review queue maxlen
EVAL_REVIEW_LABEL_MAXLEN 5000 review label Stream maxlen
EVAL_REVIEW_DEDUPE_TTL_SEC 604800 review dedupe TTL
EVAL_CALIBRATION_MIN_CORR 0.5 calibration gate
REVIEWER_ID git user.email human review 식별자
LLM_PROPOSE_MODEL LLM_JUDGE_MODEL proposal model
LLM_PROPOSE_MAX_TOKENS 1024 proposal max tokens
EVAL_TOURNAMENT_MAX_MATCHES 50 tournament match cap
EVAL_TOURNAMENT_MIN_CASES 10 proposal 최소 archive cases
PROMPT_VARIANT_ID unset 운영 prompt variant 선택

16. Alert와 Monitoring

Worker는 다음 종류의 alert를 보낼 수 있다.

Alert kind 의미
latency 최근 shadow eval latency p95 초과
llm-error-rate LLM judge 실패율 상승
eval-score-drop baseline 대비 eval score 하락
eval-drift 24h vs 7d slice score drift
endpoint-down LLM circuit breaker open
archive-stalled MongoDB archive 연속 실패

Alert는 lolympus-agent.alert NATS subject로 발행되고, dedupe key로 rate limit된다.

17. 장애 확인 Runbook

17.1 Bootstrap에서 certificate has expired

증상:

[Bootstrap] Fatal startup error
message: certificate has expired
code: CERT_HAS_EXPIRED

src/main.ts 기준 NATS 연결이 첫 외부 TLS 연결이다. ✓ NATS connected 로그가 없으면 NATS_ENDPOINT 인증서가 1순위 원인이다.

확인:

node --trace-warnings --import tsx src/main.ts

인증서 날짜 확인:

openssl s_client -connect <host>:<port> -servername <host> </dev/null 2>/dev/null \
  | openssl x509 -noout -dates -subject

✓ NATS connected 이후 같은 오류가 나면 다음 후보는 Garnet 또는 MongoDB다.

17.2 LLM endpoint warning

증상:

[LLM] Endpoint unavailable via circuit breaker
[LLM] Request error
[LLM] All endpoints failed

확인 순서:

  1. CLI_PROXY_API_URLS
  2. OPENROUTER_API_KEY, OPENROUTER_API_URL
  3. AGENT_LLM_API_URLS
  4. LLAMA_SERVER_API_URL
  5. provider별 API key

npm run eval -- --skip-llm-judge는 LLM judge를 생략하지만 실제 응답 생성 LLM은 여전히 호출될 수 있다. endpoint가 모두 실패하면 template/fallback 경로로 통과할 수 있다.

17.3 MongoDB 미설정

Worker가 다음과 비슷한 로그를 남긴다.

MongoDB connection string missing; eval archive/drift/promote disabled

영향:

  • 실시간 응답은 가능
  • shadow eval result Stream은 쌓임
  • archive, drift, promote, calibration, tournament는 제한됨

필요 env:

MONGODB_CONNECTION_STRING=
MONGODB_PROJECT_ID=

17.4 Review queue가 밀림

확인:

npm run eval:review -- --limit=5

stale pending item 정리:

npm run eval:review -- --reset-pending

같은 케이스가 반복 라우팅되면 dedupe TTL과 cursor를 확인한다.

lolympus-agent:eval:review:cursor
lolympus-agent:eval:review:dedupe:{evalStreamId}

17.5 Archive stalled

archive-stalled alert가 뜨면 MongoDB 연결과 index 생성 권한을 확인한다.

관련 cursor:

lolympus-agent:eval:archive:cursor
lolympus-agent:eval:review:label-archive:cursor

cursor가 진행되지 않으면 worker가 다음 tick에서 재시도한다.

18. 운영 원칙

  • 실시간 응답 경로는 가능한 짧게 유지한다.
  • Evaluation은 Redis Stream을 통해 비동기로 처리한다.
  • Golden set 승격은 사람이 직접 결정한다.
  • Prompt variant 운영 반영은 tournament 결과와 eval smoke를 본 뒤 결정한다.
  • 자동 rollback이나 자동 merge는 하지 않는다.
  • 모든 timestamp는 UTC ISO-8601을 사용한다.