부록 D. 개발자 부록

본문의 🔧 개발자 노트를 한곳에 모으고 확장합니다. 비개발 독자는 건너뛰어도 됩니다. 구체적 API 문법·파라미터명·기능명은 제공자·버전마다 다르므로, 반드시 자신이 쓰는 모델의 공식 문서를 확인하세요. 여기서는 개념과 패턴에 집중합니다.

D.1 구조화 출력 (Structured Output)

복잡한 스키마를 반드시 지켜야 한다면, 프롬프트로 부탁하는 것보다 제공자의 구조화 출력/JSON 모드 기능이 안전합니다(8장). 이 기능들은 디코딩 단계에서 스키마를 강제해 파싱 실패를 크게 줄입니다.

패턴:

• 단순 JSON: 프롬프트로 스키마 명시 + "JSON만, 코드펜스 없이" + 출력 prefill({)
• 복잡·필수 스키마: 구조화 출력 기능 사용 (스키마를 API에 직접 전달)
• 출력 파싱: 정규식으로 긁지 말고 구조화 데이터로 다루기 (안정적)

주의: 지나치게 엄격한 형식 강제는 복잡한 작업에서 추론 여지를 좁혀 품질을 해칠 수 있음(8장). 형식과 내용 정확성은 별개 축으로 검증.

D.2 샘플링 파라미터 (temperature 등)

핵심(2·22장): 일관성은 프롬프트(모호함 제거·형식 고정)로 먼저 잡고, 파라미터는 모델 가이드를 확인해 보조적으로. "낮은 temperature=항상 정확"은 미신.

D.3 메시지 구조와 멀티턴

• 시스템 메시지: 역할·원칙(27장). 보통 맨 앞·정적 → 캐싱 유리.
• user/assistant 교대: 멀티턴은 이전 메시지를 누적해 매번 전송(15장). 모델은 턴 간 기억이 없으므로 상태는 직접 관리.
• few-shot: user/assistant 쌍으로 예시 구성(7장). 형식 일관 필수.

D.4 프롬프트 캐싱

반복되는 앞부분(시스템 프롬프트·공통 예시·고정 자료)을 캐싱하면 비용·지연 절감(31장). 원칙:

• 정적 콘텐츠를 앞쪽, 가변 콘텐츠(사용자 입력)를 뒤쪽에 배치
• 이는 14장 배치·27장 시스템 프롬프트 설계와 일치 — 좋은 구조가 캐싱에도 유리
• 절감 폭은 제공자·캐시 적중률에 따라 다름. 공식 문서로 확인

D.5 도구 사용 / function calling

개념(26장): 모델에 도구 명세(이름·설명·입력 스키마)를 주면, 모델이 필요 시 구조화된 호출을 냄. 시스템이 실행 후 결과를 돌려주면 모델이 이어받음.

프롬프트 핵심:

• 도구 설명을 명확히(5장이 도구 설명에도 적용) — 모델의 선택 근거
• 도구가 여럿이면 용도 경계 분명히
• 도구 결과를 컨텍스트에 넣을 때 3부 원칙(필요한 것만, 깨끗하게)
• 모호한 설명 → 엉뚱한 도구 호출 또는 누락

D.6 RAG (검색 증강 생성)

3부 컨텍스트 원칙의 자동화(26장). 흐름: 질문 → 관련 문서 검색 → 컨텍스트 삽입 → 근거 기반 생성.

품질 레버:

• 검색 품질(관련된 것을 가져오는가)이 최우선 — 좋은 검색=좋은 컨텍스트
• 검색 조각 배치: 관련성 높은 것을 양 끝(특히 질문 직전), 재정렬(re-ranking) (14장 중간 소실)
• 프롬프트: "자료에만 근거", "자료 우선", "없으면 모른다", 출처 표시(16장)
• 환각은 줄 뿐 사라지지 않음 → 인용-원문 대조 검증

D.7 컨텍스트 관리 4전략 (13, 17장)

장기·에이전트 작업(28장)에서 매 단계 적용. "컨텍스트를 유한 자원으로"가 핵심.

D.8 평가 자동화 (23장)

• 데이터셋: 대표 입력 + 기대 결과 고정
• 회귀 테스트: 프롬프트·모델 변경 시 전체에 자동 실행, 지표 산출
• 채점 방식:
  • 정답 대조(분류·추출): 정확도·정밀도·재현율
  • 규칙 기반(형식·길이): 파싱 성공률·제약 준수율
  • LLM-as-judge: 다른 모델로 채점 — 편리하나 채점 모델 편향 주의, 사람 보정
• 모델 스냅샷 고정으로 평가 조건 일정 유지(22장)

D.9 프로덕션 운영 체크리스트

• [ ] 프롬프트를 코드처럼 버전 관리(git 등), 한곳에 모으기(30장)
• [ ] 모델 스냅샷 고정 — 버전 변화로 동작 바뀜 방지(22장)
• [ ] 평가 세트 상시 유지 — 모델 이전 시 즉시 비교(33장)
• [ ] 변경은 한 번에 하나 + 회귀 테스트(23, 30장)
• [ ] 안전: 권한 최소화·입력 신뢰 경계·출력 검증·PII 마스킹·모니터링(32장)
• [ ] 에이전트: 멈춤 조건·사람 승인·관찰 가능성·궤적 평가(28장)
• [ ] 비용: 캐싱·모델 라우팅·출력 길이 관리(31장)
• [ ] 모델 이전: 점진적 롤아웃·마이그레이션 노트 확인(33장)

D.10 Claude API에서 AI 기능 만들기 (참고)

Claude API로 애플리케이션을 만들 때 자주 쓰는 패턴(개념 수준):

• 구조화 데이터가 필요하면 시스템 프롬프트에서 "JSON만 출력"을 명확히 하고 응답을 안전하게 파싱
• 멀티턴은 전체 대화 기록을 매 요청에 포함(상태 직접 관리)
• 도구·검색을 결합해 최신성·정확성 보완
• 구체적 모델 문자열·파라미터·기능명은 공식 문서에서 확인 (빠르게 변함)

모든 구체 수치·문법·기능명은 변합니다. 이 부록은 개념 지도이고, 실제 구현 전 공식 문서로 최신 내용을 확인하세요.

목차로 · 다음 부록 → E. 용어집