AI 서비스 엔지니어링: Track A
3주차 · LLM API와 프롬프트
CodeCompose · 2026-08-07
자연어로 받으면 vs 계약으로 받으면
| 구분 | 자연어 | 계약 |
|---|---|---|
| 모델 원출력 | "화요일은 순대국밥 어떠세요? 약 4,000mg 😊" | {"day":"화","sodium_mg":4230.0,...} |
| 코드가 쥐는 것 | 그 문자열 그대로 (아직 데이터가 아님) | 검증을 마친 Pydantic 객체 |
| 값을 꺼내려면 | 정규식·json.loads로 캐낸다 | meal.sodium_mg > 800처럼 바로 비교 |
| 형식이 틀리면 | 내가 알아채고 내가 고친다 | 검증 실패가 모델에게 되돌아가 자동 재시도 |
오른쪽은 “예쁘게 받기”가 아닙니다.
다음 단계의 코드가 곧바로 소비할 수 있는 데이터이고, 이 차이가 오늘 만들 파이프라인 전체를 지탱합니다
운영안 요구사항과 이 예제의 대응
| 요구사항 | 드러나는 자리 |
|---|---|
| LiteLLM 멀티 프로바이더 | 계획자 openai/... · 검증자 anthropic/..., 역할마다 회사가 갈립니다 |
| 역할별 모델 env 분리 | PLANNER_MODEL / VALIDATOR_MODEL / VALIDATOR_FALLBACKS |
| LiteLLM 폴백 | 검증자 장애 = 파이프라인 정지. 폴백이 살립니다 |
| structured output (instructor) | 계획자 출력 = 검증자 입력, 검증자 출력 = 계획자의 다음 입력 |
| 프롬프트 패턴 | 0단(나쁜 프롬프트) → 컨텍스트 주입 → 스키마 → few-shot 사다리 |
시스템 전체 그림
flowchart TB
U(["사용자"]) --> UIS
subgraph uibox["ui 컨테이너 — 사전 구축"]
UIS["Streamlit (폼형)<br/>조건 폼 + 요청사항 한 줄<br/>결과: 식단표 · 위반 리포트<br/>suggestion 원클릭 채택"]
end
UIS -->|"HTTP POST /plan<br/>(compose 네트워크: http://api:8000)"| API
subgraph app["api 컨테이너 — week03-meal-planner (헤드리스)"]
API["FastAPI /plan"]
subgraph pipeline["pipeline/ — 코드가 제어하는 고정 흐름"]
P["계획자 호출<br/>(PLANNER_MODEL)"]
V["검증자 호출<br/>(VALIDATOR_MODEL)"]
X["코드 크로스체크<br/>(환산 재계산)"]
D{"통과?"}
RV["위반 목록을<br/>계획자에 회신"]
end
LLMW["llm/ LiteLLM 래퍼<br/>폴백 체인 · 비용 로그"]
DATA[("data/foods.json<br/>식약처 영양DB 스냅샷<br/>음식·영양·1인분량")]
end
API --> P
P --> V --> X --> D
D -- "아니오 (상한 3회)" --> RV --> P
D -- 예 --> OUT["최종 식단 + 검증 리포트"]
OUT --> UIS
P <--> LLMW
V <--> LLMW
P -. "후보 음식 목록 주입" .- DATA
X -. "수치 대조" .- DATA
LLMW <--> OAI["OpenAI<br/>(계획자)"]
LLMW <--> ANT["Claude<br/>(검증자)"]
LLMW -. "폴백" .-> GEM["Gemini"]structured output은 어디서 나오나
모델의 출력을 자유 텍스트가 아니라 검증된 타입 데이터로 받는 것
- 이 시스템에서는 LLM 호출 지점 두 곳 모두가 structured output
- 입구부터 타입:
/plan의 입력도 Pydantic (UI 폼과 1:1 대응)
class PlanRequest(BaseModel): # ← /plan의 입력
kcal_min: int = 500
kcal_max: int = 800
sodium_limit_mg: int = 800 # 저녁 몫 나트륨 예산
protein_min_g: int = 25
request: str = "" # 자유 요청사항 — 비우면 순수 조건만으로
# 상태는 이 필드가 전부 계획자의 출력 계약: MealPlan
class Meal(BaseModel):
day: str # "월"
food_code: str # "D101-004310000-0001"
food_name: str # "국밥_순대국밥"
serving_g: int # 900 (1인분량)
calories_kcal: float # 675.0 (100g값 × 9 환산)
protein_g: float
sodium_mg: float
reason: str # 선정 이유 한 줄
class MealPlan(BaseModel): # ← 계획자의 출력
meals: list[Meal] # 7개 검증자의 출력 계약: ValidationReport
class Violation(BaseModel):
type: Literal["존재하지_않는_음식", "환산_오류", "제약_위반", "중복"]
day: str
food_code: str
evidence: str # "470mg/100g × 900g = 4,230mg > 800mg"
severity: Literal["high", "medium", "low"]
suggestion: str # 수정 제안 한 줄
class ValidationReport(BaseModel): # ← 검증자의 출력
passed: bool
violations: list[Violation]evidence필드가 판정에 근거를 강제합니다
호출은 이렇게 바뀝니다
# 0단 (나쁜 예): 문자열이 돌아옴 — 파싱·검증·재시도 전부 내 몫
text = litellm.completion(model=..., messages=...).choices[0].message.content
# instructor: 검증된 객체가 돌아옴 — 스키마 불일치면 자동 재시도
plan: MealPlan = client.chat.completions.create(
model=os.environ["PLANNER_MODEL"],
response_model=MealPlan, # ← 이 한 줄이 structured output
messages=[...],
)
plan.meals[1].sodium_mg # 바로 코드에서 사용 — 파싱 코드 없음 왜 두 출력 모두 structured여야 하는가
둘 다 사람이 읽는 글이 아니라 다음 코드가 소비하는 데이터
flowchart LR
PL["계획자"] -->|"MealPlan"| CODE1["코드: 검증자에 전달<br/>크로스체크: sodium_mg 재계산<br/>API: 최종 응답 직렬화"]
VA["검증자"] -->|"ValidationReport"| CODE2["코드: passed로 루프 분기<br/>violations를 계획자의<br/>다음 입력으로 회신"]
CODE2 -->|"재계획 요청"| PLpassed필드 하나로 코드가 루프를 돌릴지 결정합니다evidence·suggestion은 계획자의 다음 프롬프트에 그대로 들어갑니다
시작점 내려받기
클론이 아니라 태그 ZIP: 버전이 고정되어 문서와 같은 상태에서
- 클론하면 완성본 이력까지 딸려 와 정답을 먼저 보게 됩니다
- 버전별 코드는 저장소의 Tags 페이지에서: https://github.com/2026-ai-service-engineering-a/week03-meal-planner/tags
- 태그마다
zip링크가 붙어 있어 필요한 버전을 골라 내려받으면 됩니다 - 지금은 v0.1의 zip을 받아 압축을 풉니다
① 코드 열고 프롬프트 설명
v0.1에 포함된 examples/naive_plan.py 전문
"""이렇게 하면 안 되는 이유를 보여주는 파일 — 지우지 말 것"""
import os, litellm
resp = litellm.completion(
model=os.environ["PLANNER_MODEL"],
messages=[{
"role": "user",
"content": "일주일 저녁 식단을 나트륨 적게 JSON으로 짜줘",
}],
)
print(resp.choices[0].message.content)- 스키마 없음, 데이터 없음, “JSON으로”라는 부탁뿐
- 그럴듯해 보이는 것이 함정입니다
1차 지시
식단 플래너의 1단계: 계획자를 만들어줘.
- POST /plan 입력: 구조화된 조건(칼로리 범위·나트륨 한도·단백질 최소)과
자유 요청사항 문자열(request). 계획자 프롬프트에 둘 다 반영해라 —
request가 비어 있으면 조건만으로 생성. 응답은 저녁 7끼 식단 초안
- 계획자 LLM 호출은 LiteLLM 경유, 모델은 환경변수 PLANNER_MODEL
- structured output은 instructor를 사용해라. Pydantic 스키마:
MealPlan — 7개 항목, 각 항목은 요일, 식품코드, 식품명,
1인분 기준 환산값(에너지 kcal·단백질 g·나트륨 mg), 선정 이유 한 줄
- 프롬프트에는 data/foods.json에서 조건에 맞는 후보 음식 목록
(코드·이름·100g 영양값·1인분량)을 넣어줘라 — 목록에 없는 음식 금지
- 100g→1인분 환산 규칙과 예시 2개(few-shot)를 시스템 프롬프트에 포함해라
- 제약 기본값: 한 끼 500~800kcal, 단백질 25g 이상, 나트륨 800mg 이내,
같은 대표식품 주 2회 이하 — 시스템 프롬프트에 명시
- 디버그 로그: LOG_LEVEL=debug일 때 모든 LLM 호출의 조립된 프롬프트 전문,
모델 원출력, instructor 재시도 과정을 로그로 남겨라
- 아직 검증은 만들지 마 — 다음 단계
- 작업 단위마다 커밋하면서 진행해라 — 스키마 → 계획자 호출 →
엔드포인트 연결 순으로 커밋을 나누고, 각 커밋 메시지에 의도를 남겨라 코드에서 이 부분
| 파일 | 보는 곳 | 왜 중요한가 |
|---|---|---|
schemas/meal.py | class MealPlan(BaseModel) | 브리핑에서 본 그 스키마, 곧 계약서 |
llm/client.py | instructor.from_litellm(...) | LiteLLM 위에 instructor를 씌우는 한 줄. 멀티 프로바이더 + 스키마 보증의 결합점 |
pipeline/planner.py | 후보 필터 → 프롬프트 조립 → response_model=MealPlan | 조건으로 foods.json을 거르고, 텍스트로 펴서, 계약과 함께 보냅니다. 이 함수가 계획자의 전부 |
app/main.py | /plan에서 PlanRequest 수신 → planner 호출 | 입구의 타입 보증(Pydantic)과 출구의 타입 보증(instructor)이 만나는 곳 |
2차 지시
2단계: 검증자와 수정 루프를 추가해줘.
- 검증자 LLM 호출은 VALIDATOR_MODEL (계획자와 다른 프로바이더).
LiteLLM 경유, 폴백 체인은 VALIDATOR_FALLBACKS 순서로
- 검증자 입력: MealPlan + 각 음식의 원본 100g 영양값·1인분량
- 검증자 출력도 instructor 스키마로:
ValidationReport — 통과 여부, 위반 목록
(위반 유형: 존재하지 않는 음식 / 환산 오류 / 제약 위반 / 중복,
대상 요일·식품코드, 근거 수치, 심각도, 수정 제안 한 줄)
- 검증자와 별개로 코드 크로스체크를 넣어라:
환산과 합계는 순수 함수로 재계산해서 검증자 결과와 대조.
환산 함수에는 유닛테스트 작성
- 수정 루프: 위반 목록을 계획자에 되돌려 재생성, 최대 3회.
3회 안에 통과 못 하면 마지막 안과 위반 목록을 함께 반환 (정직한 실패)
- /plan 응답에 최종 식단 + 검증 리포트 + 시도 횟수 +
시도별 위반 이력(history) 포함 — 루프가 돌았다는 증거를 응답에 남겨라
- 작업 단위마다 커밋하면서 진행해라 — 검증자 스키마·호출 →
크로스체크·테스트 → 수정 루프 연결 순으로 커밋을 나눠라 코드에서 이 부분
| 파일 | 보는 곳 | 왜 중요한가 |
|---|---|---|
schemas/validation.py | evidence·suggestion 필드 | 판정에 근거를 강제하는 계약 |
pipeline/validator.py | model=VALIDATOR_MODEL + response_model=ValidationReport | 계획자와 같은 모양, 다른 회사. 교차 검증이 코드에서는 이 한 줄 차이 |
pipeline/crosscheck.py | 환산·합계 순수 함수 | LLM 없이 도는 산수. 테스트가 붙는 곳 |
pipeline/loop.py | for attempt in range(3)과 위반 회신 조립 | 수정 루프의 전부. 상한 3회가 하드코딩이 아니라 눈에 보이는 규칙 |
v1.0 내려받아 띄우기
Tags 페이지에서 v1.0의 zip
https://github.com/2026-ai-service-engineering-a/week03-meal-planner/tags
cd week03-meal-planner-1.0
cp ../week03-meal-planner-0.1/.env .
docker compose -f docker-compose.yml -f docker-compose.dev.yml up- v0.1을 띄워 둔 상태라면 먼저 내립니다
.env는 v0.1 폴더의 것을 복사- 같은 지시를 직접 돌려 내 버전을 만들어 봤다면 파일 이름과
로그 마커가 문서와 다를 수 있습니다.
- 요구사항을 만족하면 그것대로 성공
v0.1에서 무엇이 달라졌나
두 회전이 더한 것이 전부
| 구분 | v0.1 | v1.0 |
|---|---|---|
/plan | 목 응답 | 계획자 → 검증자 → 크로스체크 → 수정 루프 (상한 3회) |
| 응답 | 고정 문자열 | meals + report + attempts + history |
api/ 구성 | app/main.py 목 하나 | schemas/ llm/ pipeline/ tests/ 추가 |
| API 키 | 없어도 뜸 | 실호출 (2개 이상 권장) |
| UI·데이터 | 사전 구축 UI · foods.json | 변경 없음 (헤드리스 분리의 증명) |
| PROMPT.md | 자리만 | 지시 프롬프트 2개 누적 |
- 명령 (참조만 하세요)
diff -r week03-meal-planner-0.1 week03-meal-planner-1.0 | less 계획자 층: 데이터의 여행
지도를 먼저 걸어두고, 각 지점을 명령 → 실물로 엽니다
flowchart TB
A["① UI 폼 제출<br/><i>{kcal: 500~800, sodium: 800,<br/>protein: 25, request: ''}</i>"]
B["② PlanRequest 객체<br/>FastAPI+Pydantic이 타입 보증<br/>(틀린 입력은 여기서 422)"]
C["③ 계획자 프롬프트 (텍스트)<br/>system: 역할·제약·환산 few-shot<br/>user: 조건 + 후보 음식 목록 주입"]
D["④ 모델 원출력 (JSON 문자열)<br/>instructor가 수신"]
E["⑤ MealPlan 객체<br/>스키마 검증 통과 — 타입 있는 데이터"]
F["⑥ HTTP 응답 JSON<br/>UI가 식단표로 렌더링"]
A -->|HTTP| B -->|"코드가 텍스트로 변환"| C -->|"LiteLLM → OpenAI"| D -->|"검증"| E -->|"직렬화"| F관문 ②: 틀린 입력은 LLM에 가기도 전에 죽는다
- 명령
curl -s localhost:8000/plan -X POST -H 'Content-Type: application/json' \
-d '{"kcal_min":500,"kcal_max":"많이","sodium_limit_mg":800,"protein_min_g":25}' | jq- 결과
{ "detail": [ { "loc": ["body", "kcal_max"],
"msg": "Input should be a valid integer", "input": "많이" } ] }- LLM 요금이 나가기 전에 Pydantic이 공짜로 막았습니다. 첫 번째 관문
정상 호출 → 응답 실물
- 명령
curl -s localhost:8000/plan -X POST -H 'Content-Type: application/json' \
-d '{"kcal_min":500,"kcal_max":800,"sodium_limit_mg":800,"protein_min_g":25,"request":""}' | jq- 결과
{
"meals": [
{ "day": "월", "food_code": "D101-007280000-0001", "food_name": "김밥_소고기",
"serving_g": 250, "calories_kcal": 447.5, "protein_g": 16.2,
"sodium_mg": 667.5, "reason": "단백질 보강과 나트륨 여유를 함께 확보" },
...
],
"report": { "passed": true, "violations": [] },
"attempts": 1,
"history": []
}- 무난한 조건이라 1차 통과:
attempts: 1,history는 빈 배열
관문 ③·④: 모델이 실제로 본 것과 뱉은 것
LOG_LEVEL=debug: 관측 가능성도 요구사항이었습니다
- 명령
docker compose logs api | grep -A 40 "PLANNER PROMPT"- 결과
[debug] PLANNER PROMPT ─ system:
너는 식단 계획자다. 규칙: ... 환산 예시) 순대국밥 100g=75kcal, 1인분 900g → 675kcal ...
[debug] PLANNER PROMPT ─ user:
조건: 500~800kcal, 나트륨≤800mg, 단백질≥25g
후보 목록: [D101-007000000-0001 김밥 140kcal/100g 1인분230g Na307mg] [...]
[debug] PLANNER RAW OUTPUT: {"meals":[{"day":"월", ... 나오지 않을 때: 실패의 두 층
flowchart TB
CALL["LLM 호출"] --> OK{"응답이 왔는가?"}
OK -- "아니오 — 429·5xx·타임아웃<br/>(모델 층 실패)" --> FB["LiteLLM 폴백<br/>다음 프로바이더로 교체"]
FB --> CALL
OK -- 예 --> VALID{"스키마를 통과했는가?"}
VALID -- "아니오 — 필드 누락·타입 불일치<br/>(형식 층 실패)" --> RETRY["instructor 재시도<br/>검증 오류를 담아 같은 모델에 재요청"]
RETRY --> CALL
VALID -- 예 --> OBJ["검증된 객체 — 파이프라인 진행"]- 모델 층 실패(폴백)의 실물은 잠시 뒤 모의 장애로 봅니다
instructor 재시도 관찰
- 명령
docker compose logs api | grep -B 2 -A 8 "INSTRUCTOR RETRY"- 결과
[debug] PLANNER RAW OUTPUT: {"meals":[{"day":"월요일", ... ← Literal["월",...] 위반
[debug] INSTRUCTOR RETRY 1/2 ─ validation error:
meals.0.day: Input should be '월','화',... [type=literal_error]
[debug] (오류 내용을 담아 재요청)
[debug] PLANNER RAW OUTPUT: {"meals":[{"day":"월", ... ← 통과- 형식이 틀리면 사람이 고치는 것이 아니라, 오류가 모델에게 되돌아가고 모델이 고칩니다.
- 그것이 자동 재시도의 실체
수정 루프: 검증자가 계획자의 실수를 잡아낸다
sequenceDiagram
participant API as /plan (코드가 지휘)
participant PL as 계획자 (OpenAI)
participant VA as 검증자 (Claude)
participant CK as 크로스체크 (코드)
API->>PL: 요구 + 후보 목록 + 제약
PL-->>API: MealPlan v1 (7끼)
API->>VA: MealPlan v1 + 원본 수치
VA-->>API: 위반 2건 — 화요일 나트륨 초과(근거 수치), 목·일 중복
API->>CK: 환산·합계 재계산
CK-->>API: 검증자 판정과 일치 확인
API->>PL: 위반 목록 회신 → 재계획
PL-->>API: MealPlan v2 (국밥 → 비빔밥 교체)
API->>VA: 재검증
VA-->>API: 통과
API-->>API: 최종 응답 (식단 + 리포트 + 시도 2회)위반을 유도하는 호출
국물 요리 유도로 나트륨 위반이 거의 확실히 발생합니다
발생하지 않을 때도 있습니다. 그럴 때는 kcal_max를 600으로 하면 나타나기도 합니다.
- 명령
curl -s localhost:8000/plan -X POST -H 'Content-Type: application/json' \
-d '{"kcal_min":500,"kcal_max":800,"sodium_limit_mg":800,"protein_min_g":25,
"request":"국물 요리 위주로 짜줘"}' | jq- 결과
{
"meals": [ ... 최종 7끼 ... ],
"report": { "passed": true, "violations": [] },
"attempts": 2,
"history": [
{ "attempt": 1, "passed": false, "violations": [
{ "type": "제약_위반", "day": "화", "food_code": "D101-004310000-0001",
"evidence": "순대국밥 470mg/100g × 900g = 4,230mg > 800mg",
"severity": "high", "suggestion": "국물이 적은 밥류(비빔밥 등)로 교체" } ] }
]
} 검증자가 실제로 받은 것·뱉은 것
- 명령
docker compose logs api | grep -A 30 "VALIDATOR PROMPT"- 결과
[debug] VALIDATOR PROMPT ─ user:
식단: 화 순대국밥(D101-0043...) serving 900g 칼로리 675 나트륨 4230 ...
원본 수치: 순대국밥 100g당 75kcal, Na 470mg, 1인분량 900g ...
[debug] VALIDATOR RAW OUTPUT: {"passed": false, "violations":[{"type":"제약_위반", ...- 1회전의 출력 객체(MealPlan)가 텍스트로 풀려서 2회전의 입력이 됐습니다
- 스키마가 배선이라는 말의 실물
위반이 계획자에게 되돌아간 실물
- 명령
docker compose logs api | grep -A 15 "PLANNER PROMPT (revision)"- 결과
[debug] PLANNER PROMPT (revision) ─ user:
직전 식단에서 다음 위반이 발견됨. 반영해서 다시 계획해라:
- [high] 화요일 순대국밥: 470mg/100g × 900g = 4,230mg > 800mg
제안: 국물이 적은 밥류(비빔밥 등)로 교체- 검증자의
evidence·suggestion필드가 계획자의 입력 문장이 되는 순간 - structured output의 필드 하나가 시스템을 관통합니다
조합 교체: env만으로
- 명령
# .env: PLANNER_MODEL=openai/gpt-... → PLANNER_MODEL=gemini/gemini-...
docker compose up -d --force-recreate api # env 변경은 재기동으로 반영
curl -s localhost:8000/plan -X POST ... | jq '.meals[0]' # 같은 요청 재실행- 결과
[debug] LLM CALL ─ role=planner model=gemini/gemini-... ← 로그에서 확인- 코드는 한 줄도 안 바뀌었습니다.
- diff가 없다는 것(
git status가 깨끗함)이 이 시연의 증거
- diff가 없다는 것(
폴백: 모의 장애
flowchart LR
VC["검증자 호출"] --> M1["VALIDATOR_MODEL<br/>(고장난 이름으로 변경)"]
M1 -->|실패| M2["폴백 1: gemini/..."]
M2 -->|성공| OK["검증 계속 — 파이프라인 생존"]
M2 -.->|실패 시| M3["폴백 2: openai/..."] -.-> ERR["정직한 에러"]# .env: VALIDATOR_MODEL=anthropic/claude-... → anthropic/no-such-model
docker compose up -d --force-recreate api
curl -s localhost:8000/plan -X POST ... | jq '.report.passed' # 그래도 검증이 됨 폴백 로그
- 명령
docker compose logs api | grep -A 3 "FALLBACK"- 결과
[warn] LLM CALL FAILED ─ role=validator model=anthropic/no-such-model (NotFoundError)
[info] FALLBACK ─ validator → gemini/gemini-... (VALIDATOR_FALLBACKS[0])
[debug] VALIDATOR RAW OUTPUT: {"passed": ...- 응답은 정상, 로그에만 장애의 흔적
- 사용자는 프로바이더 장애를 몰랐습니다.
- 검증자가 죽었는데 서비스는 살았고, 검증도 됐습니다
추가 과정 (v1.5): 관측을 얹는다
라이브 세션 범위 밖 · 선택 과정
v1.0으로 이번 주 목표는 완결, v1.5는 그 위에 관측(observability)과 재현 편의
Tags 페이지에서 v1.5의 zip
https://github.com/2026-ai-service-engineering-a/week03-meal-planner/tags
/plan/stream: 진행은 보여주되 무상태는 지킵니다
- 명령
curl -sN localhost:8000/plan/stream -X POST -H 'Content-Type: application/json' \
-d '{"kcal_min":500,"kcal_max":800,"sodium_limit_mg":800,"protein_min_g":25,
"request":"국물 요리 위주로 짜줘"}'- 결과
data: {"event":"progress","stage":"planner","detail":"계획자 호출 — 식단 초안 생성 (시도 1/3)",...}
data: {"event":"progress","stage":"validator",...}
...
data: {"event":"result","data":{...}}- 후보 선별 → 계획자(시도 n/3) → 검증자 → 위반 회신이 SSE 이벤트로
- 서버에 작업 상태 저장 없음: 진행 상태는 HTTP 연결 안에만
/plan계약은 그대로: 기존 소비자를 깨지 않는 확장
v0.1: 시연 시작점 (사전 준비)
week03-meal-planner (v0.1)
├── api/
│ ├── app/main.py # FastAPI — /plan 목 ("아직 영양사가 출근 전입니다")
│ ├── Dockerfile # uv 기반 (2주차 패턴 재사용)
│ └── pyproject.toml # litellm, instructor, pydantic, fastapi, pytest
├── ui/
│ ├── app.py # Streamlit 폼형 UI (사전 구축)
│ └── Dockerfile
├── data/foods.json # 식약처 영양DB 스냅샷 (전처리 완료, 출처 명기)
├── scripts/prepare_data.py # 원본 엑셀 → foods.json 전처리
├── examples/
│ ├── naive_plan.py # 0단 나쁜 프롬프트 (의도된 실패 예제)
│ └── naive_parse.py # 0단 출력을 json.loads 시도 (3줄)
├── docker-compose.yml # api + ui 두 서비스 (DB 없음)
├── docker-compose.dev.yml # 개발 오버라이드
├── .env.example # 모델 3종 + 키 3종
├── PROMPT.md # 자리만
└── README.md # 실행 방법, 데이터 출처, 키 안내 v1.0: 시연 종료점
api/schemas/: MealPlan · ValidationReport (instructor용 Pydantic)api/llm/: LiteLLM 래퍼 (역할별 모델 로딩, 폴백 체인, 비용 로그)api/pipeline/: 계획자, 검증자, 크로스체크(순수 함수), 수정 루프 (상한 3회)/plan연결: 최종 식단 + 검증 리포트 + 시도 횟수 반환, 사전 구축 UI가 그대로 렌더링 (UI 코드는 v0.1에서 변경 없음)tests/: 환산·합계 순수 함수 유닛테스트PROMPT.md: 지시 프롬프트 2개 누적, PR 2개 머지 이력
v1.5: 세션 뒤 확장
- compose에
prepare-data일회성 서비스 (profiles가 tools라run으로만) /plan응답 확장:audit+llm_calls, 기존 필드는 그대로 (하위 호환)- 새 엔드포인트:
POST /plan/stream·GET /config - UI: 진행 로그, 검증 상세 표, 호출 기록 뷰어, 사이드바 모델 구성
- 데이터 스냅샷을 K-FIND 원본에서 재생성한 500종으로 교체 (순대국밥 앵커 유지, 연어 없음이라 환각 시연도 유지)
- PR 3개 머지 이력:
git log v1.0..v1.5
부록: foods.json은 어떻게 만들어졌나
재현에는 필요 없지만, 출처는 밝혀 둡니다
flowchart LR
XL["K-FIND 음식 DB 엑셀<br/>140+ 컬럼, 약 2만 행"] --> F1["필터<br/>데이터구분 = D (음식)"] --> F2["컬럼 10개 추출"] --> F3["샘플링<br/>500종"] --> J[("data/foods.json")]# 원본을 data/food_data.xlsx로 이름 변경한 뒤 (prepare-data는 v1.5부터)
docker compose run --rm prepare-data data/food_data.xlsx- 원본 엑셀은 커밋하지 않습니다. 결과물과 스크립트만 남깁니다.
- 출처와 가공 과정이 코드로 증명되는 셈
- 이 원칙이 4주차의 본격 주제가 됩니다