AI 서비스 엔지니어링: Track A
9주차 · 라이브 빌드 2: 가계부에 도구와 RAG를 얹다
CodeCompose · 2026-10-08
1회전 지시 프롬프트
#8의 첫 feature다. api에 집계 엔드포인트 둘을 더하자. Refs #8
- GET /v1/stats/frequency: from, to, category_id 또는 merchant
→ 건수, 거래가 있던 날 수, 평균 간격(일), 회당 평균 금액
- GET /v1/stats/compare: 기간 둘(a_from, a_to, b_from, b_to), category_id
→ 카테고리별 두 합계와 증감(금액·비율)
- 집계는 SQL로. 파이썬에서 거래를 불러와 세지 마라
- 걸름 규칙은 /v1/summary와 같게. 목록과 다른 거래를 세면 안 된다
- 기간 이름은 받지 마라. from/to만
- docs/api-contract.md 6장에 줄을 옮기고, docs/ai/README.md 7.2에서 지워라
- 유스케이스 → 저장소 → 라우터 순으로, 단위마다 커밋. 모델 호출은 없다 결과 봉투
모든 도구가 같은 모양으로 답합니다
{
"call_id": "call_3",
"ok": true,
"data": { "count": 7, "day_count": 5, "avg_gap_days": 1.4 },
"meta": { "row_count": 7, "truncated": false, "elapsed_ms": 38 }
}ok: false: 실패도 봉투로 모델에게 보여 줍니다 (5주차 에러 되먹임)truncated: 잘렸으면 문장으로도 알립니다. 조용히 자르면 그게 전부라고 믿습니다- 금액은 정수와 통화로.
"8,500원"같은 서식은 화면의 일입니다
2회전 지시 프롬프트
#8의 두 번째 feature다. agent에 도구를 세우자. 모델은 아직 부르지 마. Refs #8
- domain: 기간 이름(PeriodName)과 경계 계산. chat-analytics.md 5장의 표 그대로.
오늘 날짜와 타임존을 주입받는 순수 함수로. 주는 월요일에 시작한다
- domain/tools: 읽기 도구 여섯의 입력·출력 스키마와 설명.
설명은 두 줄. 둘째 줄은 "언제 이 도구를 쓰지 않는가"
- application: 도구 실행기. 이름과 인자를 받아 기간을 풀고,
api를 부르고, tools.md 3.1의 결과 봉투로 돌려준다.
실패도 봉투로(ok: false). 재시도하지 마라
- 모드별 도구 세트. query 모드에 쓰기 도구가 없다는 테스트를 넣어라
- 테스트는 가짜 api로. LLM은 어디에도 없다
- 기간 → 도구 → 실행기 → 도구 세트 순으로 커밋 요청 하나의 흐름
sequenceDiagram
participant U as ui
participant AG as agent
participant M as LLM
participant API as api
U->>AG: POST /chat "저번 주에 카페 몇 번?"
AG->>M: 질문 + query 도구 여섯
M-->>AG: count_frequency(last_week, cafe)
AG-->>U: SSE tool "세는 중…"
AG->>AG: last_week → 9/14 ~ 9/20 (코드)
AG->>API: GET /v1/stats/frequency
API-->>AG: count 7, day_count 5
AG->>M: 결과 봉투
M-->>AG: 도구 없이 답
AG->>AG: 숫자 검증
AG-->>U: SSE message "저번 주(9/14~9/20)에 7번"3회전 지시 프롬프트
#8의 마지막 feature다. 모델이 도구를 고르게 하자. Refs #8
1) LanguageModel 포트에 도구 호출 메서드. LiteLLM의 tools=로.
도구 스키마는 2회전의 Pydantic 모델에서 뽑는다. complete_json은 그대로
2) ReAct 루프. agent-loop.md 4장의 정지 조건 넷.
AGENT_MAX_STEPS, AGENT_MAX_COST_USD를 쓴다. 새 상한을 만들지 마라
3) 답의 숫자 검증. chat-analytics.md 7.2. 실패하면 문장을 버리고 표만
4) POST /chat SSE. 이벤트는 chat.md 4.1의 것만. tool 이벤트에 인자를 싣지 마라
5) ui: AGENT_BASE_URL이 있으면 agent를 부르는 ChatAgent. 화면 코드는 고치지 마라
6) questions.json 30건. 묶음은 chat-analytics.md 9장대로
- 단위 테스트는 가짜 모델로. 실제 모델 평가는 -m integration으로
- 번호마다 커밋. 각 커밋에서 make all이 통과해야 한다
- 2회전의 도구 스키마를 바꿔야 하면 먼저 말해라 받아 오는 법
미리 넣어 두지 않습니다. 0회전에서 현장에서 받습니다
- 실행
# 법령을 찾아 법령일련번호(MST)를 얻는다
curl -G "https://www.law.go.kr/DRF/lawSearch.do" \
--data-urlencode "OC=test" --data-urlencode "target=law" \
--data-urlencode "type=JSON" --data-urlencode "query=조세특례제한법"
# 조문 하나. JO = 조 번호 4자리 + 가지 번호 2자리 (제126조의2 → 012602)
curl -G "https://www.law.go.kr/DRF/lawService.do" \
-d OC=test -d target=law -d type=JSON -d MST=284389 -d JO=012602 받아 오는 법 (이어서)
- 결과 (줄임)
{ "법령": {
"기본정보": { "법령명_한글": "조세특례제한법", "시행일자": "20260918" },
"조문": { "조문단위": {
"조문내용": "제126조의2(신용카드 등 사용금액에 대한 소득공제)",
"항": [ { "항번호": "①", "항내용": "① 근로소득이 있는 거주자(…)가 …", "호": [ … ] },
{ "항번호": "②", "항내용": "② 신용카드등소득공제금액은 …", "호": [ … ] } ] } } } }OC는 이용자 키.test로도 오지만, 스크립트는 신청한 키를 환경변수로 받습니다- 조 하나에
##하나인 Markdown으로 풀고, 머리에 출처 · 법령일련번호 · 시행일자
기능 문서의 틀: 여덟 칸
docs/ai/README.md 6장 · #8의 chat-analytics.md도 이 틀
| 칸 | #11에서 |
|---|---|
| 1. 목적 | 법령을 찾아 “다음 각 호”를 손으로 따라가며 읽는다 |
| 2. 경계 | api 저장 · 검색, agent 임베딩 · 생성 · 검증. 계산은 안 한다 |
| 3. 흐름 | 색인과 질의, 두 길 |
| 4. 스키마 | 조각 id가 붙은 증강, 답 + 인용 id |
| 5. 검증과 폴백 | 인용 부분집합, abstain, 모델이 없으면 검색 결과만 |
| 6. 평가 | 질문 30 + 답 없는 질문 5 |
| 7. 결정과 이유 | 가상 문서를 뒤집은 이유도 |
| 8. 하지 않는 것 | PDF · OCR, 카드사 문서, 공제액 계산 |
실험 설계
고정: 질문 30 + 답 없는 질문 5. 계획에서 시드 13건, 3회전까지 35건
기준선: 검색 없이 LLM에게만 물은 답
넘어가는 기준: 2회전 → 3회전은 recall@5 목표를 숫자로 적어 둔다
바꾸는 것 (한 번에 하나):
청킹 고정 500자 / 항 단위 / 항 단위 + 긴 항은 호 단위
조각 머리 없음 / 조 제목 + 항 머리를 붙임
검색 방식 키워드 / 벡터 / 하이브리드
k 3 / 5 / 8
보는 것: 검색 recall@k, MRR (1·2회전) · 생성 충실도, abstain율 (3회전)모델은 공제율을 대략 압니다. 지난 연도 비율로. 기준선이 RAG를 붙이는 이유입니다
0회전 지시 프롬프트 ①
#11 문서 Q&A의 계획을 쓰자. 제품 코드는 만들지 마. Refs #11
1) 자료: 국가법령정보센터 Open API에서 아래 아홉 조문을 받아
tests/fixtures/ai/documents/laws/에 법령 하나당 Markdown 하나로 둬라.
조 하나가 ## 제목 하나. 파일 머리에 출처, 법령일련번호, 시행일자.
받는 스크립트는 scripts/fetch_laws.py 하나. 키는 LAW_API_OC 환경변수로
- 조세특례제한법 제126조의2, 같은 법 시행령 제121조의2
- 소득세법 제59조의4
- 여신전문금융업법 제16조, 제19조
- 할부거래에 관한 법률 제8조, 제16조
- 전자금융거래법 제8조, 제9조
2) 받은 자료를 재라. 항 수, 항 길이 분포, 개정 꼬리표 수 0회전 지시 프롬프트 ②
3) docs/ai/document-rag.md를 여덟 칸 틀로. 4번과 5번은 붙여서
4) 결정과 이유: 지금 정하는 것과 재서 정하는 것을 나눠라.
재서 정하는 것은 후보 값, 지표, 비교 기준을.
이슈 #11의 "가상 문서" 결정을 뒤집은 이유도
5) 정답 세트 시드: 질문 10 + 답이 없거나 일부만 있는 질문 3.
정답 조각은 법령·조·항·호 경로로.
질문은 법령의 낱말이 아니라 사람이 가계부를 보며 할 말로
6) feature 나누기: doc-store → doc-index → doc-qa → doc-tool
7) docs/ai/README.md 1장 · 7장. 계약 문서는 아직 고치지 마라
- 번호마다 커밋해라 1회전 지시 프롬프트
#11의 첫 회전이다. 법령 조각을 저장하고 키워드로 찾게 하자. 모델은 부르지 마. Refs #11
- api 마이그레이션 0005: documents(id, title, source, mst, effective_date, body),
document_chunks(id, document_id, heading, body, search_text, text_hash,
position, strategy). id는 document-rag.md의 경로 규칙대로
- 청킹 셋을 순수 함수로: fixed_500, paragraph, paragraph_item.
paragraph_item은 1,000자가 넘는 항을 호마다 나누고 조 제목과 항 머리를 붙인다.
body는 원문 그대로, search_text에서만 개정 꼬리표를 뺀다
- make docs: 자료 폴더를 읽어 세 전략의 조각을 모두 넣는다. 몇 번을 쳐도 같게
- GET /v1/documents/search?q=&k=&strategy=: pg_trgm. BM25 확장은 들이지 마라
- ui: DocumentGateway 포트, Http 구현, 메모리 대역. 문서 화면 한 장
- 측정: 정답 시드로 전략별 recall@5. 모델은 없다
- 청킹 → 마이그레이션 → 적재 → 검색 → 화면 → 측정 순으로 커밋 2회전 지시 프롬프트
#11의 두 번째 회전이다. 조각을 임베딩하고 하이브리드로 찾게 하자.
생성 모델은 부르지 마. Refs #11
- api: /v1/embeddings/pending이 document_chunks의 text_hash도 내놓게.
text_embeddings 테이블과 agent의 SyncIndex는 그대로 쓴다
- api: 문서 검색에 mode=keyword|vector|hybrid. vector는 agent가 실어 준
질문 벡터로. hybrid는 두 순위를 RRF로 합친다. 점수를 더하지 마라
- agent: POST /retrieve. 질문을 임베딩해 api에 묻고 조각 목록을 돌려준다
- ui: AGENT_BASE_URL이 있으면 문서 화면이 /retrieve를 쓰고 "AI 검색" 표시
- 측정: 청킹 3 × 방식 3 × k 3의 recall@k와 MRR 표. -m integration으로만
- 기본값은 표를 보고 내가 고른다. 고르지 말고 표까지만 만들어라 요청 하나의 흐름
sequenceDiagram
participant U as ui
participant AG as agent
participant API as api
participant M as LLM
U->>AG: POST /ask "관리비를 카드로 냈는데 공제돼?"
AG->>API: 하이브리드 검색 (질문 벡터)
API-->>AG: 조각 k개 (id · 머리 · 본문)
AG->>M: 조각을 id와 데이터 마커 안에 + 답 스키마
M-->>AG: answer · citations · abstain
AG->>AG: 인용 검증 · 숫자 대조
AG-->>U: 답 + 출처 조각3회전 지시 프롬프트
#11의 세 번째 회전이다. 검색한 조각으로 인용하는 답을 만들자. Refs #11
- agent: POST /ask. 하이브리드 검색 → 조각을 id와 함께 data_fence로 감싸
증강 → complete_json 한 번(answer, citations, abstain). 도구 호출은 쓰지 마라
- 검증: citations ⊂ 넘겨준 id, 인용 없는 주장은 abstain, 답의 숫자는
인용 조각에 있어야 한다("100분의 40"과 "40%"는 같게 본다)
- 폴백: 어떤 실패든 검색 결과만 보여 주는 응답으로 떨어진다
- ui: DocumentAnswerer 포트와 각본 대역, agent 구현. 답과 출처, 원문 펼치기
- 정답 세트를 35건으로 채워라
- 평가: 같은 모델로 기준선(검색 없음)과 RAG를 나란히. -m integration
- 프롬프트는 application/prompts/에 파일 하나로 4회전 지시 프롬프트
#11의 마지막 회전이다. 문서 검색을 채팅의 도구로 내놓자. Refs #11, Refs #8
- agent: search_documents 도구. 2회전의 /retrieve와 같은 검색을 쓴다.
설명 둘째 줄은 "내 지출 숫자가 필요하면 통계 도구를"
- 도구 세트: query 모드에만 넣는다. 다른 모드에는 넣지 마라
- 채팅 답에 문서 조각을 쓰면 출처를 붙인다. 3회전의 인용 검증을 재사용해라
- 평가: questions.json에 문서 질문 5, 통계+문서를 엮는 질문 3을 더한다.
엮는 질문은 곱한 숫자가 답에 없어야 통과
- 새 SSE 이벤트를 만들지 마라