.
This commit is contained in:
1 parent
1453433b62
commit
da76af3826
65 files changed
+11089
-143
No files matched your search
@@ -0,0 +1,510 @@
|
||||
# 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를 함께 띄운다.
|
||||
|
||||
```bash
|
||||
npm run pm2:dev
|
||||
npm run pm2:test
|
||||
npm run pm2:prod
|
||||
```
|
||||
|
||||
개발 환경 단독 실행은 기존 스크립트를 사용한다.
|
||||
|
||||
```bash
|
||||
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에 요청한다.
|
||||
|
||||
```text
|
||||
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에 저장된다.
|
||||
|
||||
```text
|
||||
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 정의:
|
||||
|
||||
```text
|
||||
tier × intent × phase
|
||||
```
|
||||
|
||||
예:
|
||||
|
||||
```text
|
||||
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
|
||||
|
||||
큐:
|
||||
|
||||
```text
|
||||
lolympus-agent:eval:review:queue
|
||||
```
|
||||
|
||||
라벨링:
|
||||
|
||||
```bash
|
||||
npm run eval:review -- --limit=20
|
||||
```
|
||||
|
||||
특정 reason만 보기:
|
||||
|
||||
```bash
|
||||
npm run eval:review -- --reason=low-score --limit=10
|
||||
```
|
||||
|
||||
stale pending item을 다시 큐에 넣기:
|
||||
|
||||
```bash
|
||||
npm run eval:review -- --reset-pending
|
||||
```
|
||||
|
||||
세션 라벨을 JSONL로 저장:
|
||||
|
||||
```bash
|
||||
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 점수의 상관을 계산한다.
|
||||
|
||||
```bash
|
||||
npm run eval:calibrate
|
||||
```
|
||||
|
||||
CI나 수동 gate로 쓰려면:
|
||||
|
||||
```bash
|
||||
npm run eval:calibrate -- --check
|
||||
```
|
||||
|
||||
`pairs < 10`이면 표본이 부족하므로 경고만 출력하고 실패 처리하지 않는다. 충분한 라벨이 쌓이면 `EVAL_CALIBRATION_MIN_CORR` 기준으로 LLM judge 신뢰도를 감시한다.
|
||||
|
||||
## 12. Report와 Promotion
|
||||
|
||||
Slice별 약한 영역 확인:
|
||||
|
||||
```bash
|
||||
npm run eval:report -- --worst=20
|
||||
```
|
||||
|
||||
최근 7일 대신 다른 window:
|
||||
|
||||
```bash
|
||||
npm run eval:report -- --worst=20 --since=24h
|
||||
npm run eval:report -- --top=20 --since=30d
|
||||
```
|
||||
|
||||
Golden candidate 확인:
|
||||
|
||||
```bash
|
||||
npm run eval:promote -- --dry-run
|
||||
```
|
||||
|
||||
Candidate 파일에 추가:
|
||||
|
||||
```bash
|
||||
npm run eval:promote
|
||||
```
|
||||
|
||||
기본 출력:
|
||||
|
||||
```text
|
||||
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를 지정한다.
|
||||
|
||||
```bash
|
||||
npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending
|
||||
```
|
||||
|
||||
archive case 수가 부족해도 강제로 실행하려면:
|
||||
|
||||
```bash
|
||||
npm run eval:propose -- --slice=tier=1,intent=photo-question,phase=photo-pending --force
|
||||
```
|
||||
|
||||
결과는 git-tracked proposal manifest로 저장된다.
|
||||
|
||||
```text
|
||||
src/eval/proposals/{variantId}.json
|
||||
```
|
||||
|
||||
### 13.2 Tournament 실행
|
||||
|
||||
Control과 variant를 비교한다.
|
||||
|
||||
```bash
|
||||
npm run eval:tournament -- --variants=control,<variantId>
|
||||
```
|
||||
|
||||
특정 archive case만 지정:
|
||||
|
||||
```bash
|
||||
npm run eval:tournament -- --variants=control,<variantId> --case-ids=1-0,2-0
|
||||
```
|
||||
|
||||
결과 조회:
|
||||
|
||||
```bash
|
||||
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를 설정한다.
|
||||
|
||||
```env
|
||||
PROMPT_VARIANT_ID=<variantId>
|
||||
```
|
||||
|
||||
반영 전에는 반드시 다음을 확인한다.
|
||||
|
||||
```bash
|
||||
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`
|
||||
|
||||
증상:
|
||||
|
||||
```text
|
||||
[Bootstrap] Fatal startup error
|
||||
message: certificate has expired
|
||||
code: CERT_HAS_EXPIRED
|
||||
```
|
||||
|
||||
`src/main.ts` 기준 NATS 연결이 첫 외부 TLS 연결이다. `✓ NATS connected` 로그가 없으면 `NATS_ENDPOINT` 인증서가 1순위 원인이다.
|
||||
|
||||
확인:
|
||||
|
||||
```bash
|
||||
node --trace-warnings --import tsx src/main.ts
|
||||
```
|
||||
|
||||
인증서 날짜 확인:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
증상:
|
||||
|
||||
```text
|
||||
[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가 다음과 비슷한 로그를 남긴다.
|
||||
|
||||
```text
|
||||
MongoDB connection string missing; eval archive/drift/promote disabled
|
||||
```
|
||||
|
||||
영향:
|
||||
|
||||
- 실시간 응답은 가능
|
||||
- shadow eval result Stream은 쌓임
|
||||
- archive, drift, promote, calibration, tournament는 제한됨
|
||||
|
||||
필요 env:
|
||||
|
||||
```env
|
||||
MONGODB_CONNECTION_STRING=
|
||||
MONGODB_PROJECT_ID=
|
||||
```
|
||||
|
||||
### 17.4 Review queue가 밀림
|
||||
|
||||
확인:
|
||||
|
||||
```bash
|
||||
npm run eval:review -- --limit=5
|
||||
```
|
||||
|
||||
stale pending item 정리:
|
||||
|
||||
```bash
|
||||
npm run eval:review -- --reset-pending
|
||||
```
|
||||
|
||||
같은 케이스가 반복 라우팅되면 dedupe TTL과 cursor를 확인한다.
|
||||
|
||||
```text
|
||||
lolympus-agent:eval:review:cursor
|
||||
lolympus-agent:eval:review:dedupe:{evalStreamId}
|
||||
```
|
||||
|
||||
### 17.5 Archive stalled
|
||||
|
||||
`archive-stalled` alert가 뜨면 MongoDB 연결과 index 생성 권한을 확인한다.
|
||||
|
||||
관련 cursor:
|
||||
|
||||
```text
|
||||
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을 사용한다.
|
||||
Reference in new issue
Block a user