AI 에이전트를 위한 좋은 스펙 작성법 원문 [LINK]
공부를 하라고, 이 글을 읽다보니 내가 모르는 것들이 너무 많았어서, AI와 공부 한 것을 기록해본다.
공부 한 것이 체화 되지 않으면 잊기때문에 수기로 한 번 쓰고, 블로그에도 다시 한번 정리하면서 습득해야겠단 생각이 들었다.
ㄱ. LLM-as-a-Judge는 어떻게 설정 할 수 있을까?
말 그대로 사람이 하던 평가 업무를 PT-4나 Claude 3.5 Sonnet 같은 고성능 LLM에게 맡기는 방법론이며, 특히 정답이 정해져 있지 않은 주관식 답변이나 챗봇의 대화 품질을 측정할 때 매우 유용하다고 한다. 설정 과정은 크게 4가지로 나뉜다고 한다.
1. 평가 프레임워크 선택 (Evaluation Framework)
가장 먼저 ‘비교 평가’를 할 것인지, ‘단일 점수 평가’를 할 것인지 결정해야한다. Reference-based Evaluation: 모범 답안(Golden Answer)을 주고, 모델의 답변이 얼마나 유사한지 평가한다.
Pairwise Comparison (비교 평가): 모델 A와 모델 B의 답변을 동시에 주고 “어느 것이 더 나은가?”를 묻는다. (가장 정확도가 높음)
Single Answer Scoring (단점수 평가): 하나의 답변에 대해 1~5점 척도로 점수를 매긴다.
ㄴ. 페르소나와 평가 기준 정의 (Prompt Engineering)
판사 역할을 할 LLM에게 명확한 가이드라인을 주어야 하며, 해당 단계가 성공의 80%를 결정한다.
Role: “당신은 AI 답변의 품질을 평가하는 전문 언어학자입니다.”
Criteria: 정확성, 유창성, 유해성, 간결함 등 구체적인 기준 제시
Scale: 점수 기준을 명확히 정의 (예: 3점은 사실관계는 맞으나 문법이 어색한 경우)
ㄷ. 편향(Bias) 제어 설정
LLM 판사는 인간과 유사한 편향을 가질 수 있어 이를 반드시 제어해야 한다.
Position Bias: 답변의 순서에 따라 점수가 달라지는 현상. (A와 B의 위치를 바꿔서 두 번 실행 후 평균 산출)
Verbosity Bias: 답변이 길기만 하면 좋은 점수를 주는 경향. (길이에 대한 페널티 부여)
Self-enhancement Bias: 자신이 생성한 스타일의 답변에 높은 점수를 주는 경향. (평가 모델을 대상 모델보다 상위 모델로 설정)
ㄹ. 자동화 파이프라인 구축 (Tools)
매번 프롬프트를 복사해서 붙여넣을 수 없으므로, 전문 프레임워크를 활용하는 것이 좋다.
| 도구 | 특징 |
| G-Eval | 논문에서 제안된 방식으로, CoT(Chain of Thought)를 사용해 평가 신뢰도를 높임. |
| DeepEval | Unit Testing 프레임워크처럼 LLM 답변을 테스트할 수 있는 오픈소스 라이브러리. |
| RAGAS | RAG(검색 증강 생성) 시스템 평가에 특화된 프레임워크. |
| LangSmith | LangChain에서 제공하는 시각화 및 평가 추적 도구. |
2. 적합성 스위트는 뭘까?
특정 제품, 서비스 또는 AI 모델이 정해진 표준이나 사양(Specification)을 엄격하게 준수하는지 검증하기 위한 테스트 도구들의 집합을 의미한다. LLM 문맥에서는 주로 모델이 특정 프로토콜을 따르는지, 혹은 특정 작업 수행 능력이 기준치에 도달했는지 확인하는 ‘시험지 세트’라고 이해하면 쉽다고 했다.
ㄱ. 주요 구성 요소
적합성 스위트는 단순한 테스트를 넘어 보통 다음 3가지를 포함
테스트 케이스 (Test Cases): 표준 준수 여부를 확인하기 위한 입력 데이터 세트
검증 도구 (Validation Tools): 결과값이 기준에 부합하는지 자동으로 체크하는 소프트웨어
표준 문서 (Standard Docs): 무엇이 ‘합격’이고 ‘불합격’인지 정의한 상세 규격
ㄴ. LLM 분야에서의 예시
LLM 시스템을 구축할 때 ‘적합성 스위트’는 다음과 같은 용도로 쓰임
API 적합성: 예를 들어, 사내 구축한 로컬 모델이 OpenAI API 규격과 100% 호환되는지 확인하는 테스트입니다. (헤더, 엔드포인트, 응답 JSON 구조 등)
RAG 적합성: 검색 증강 생성 시스템이 기업의 보안 가이드라인이나 답변 형식(예: “반드시 출처를 표기할 것”)을 엄격히 지키는지 확인하는 일련의 테스트셋입니다.
언어/도메인 적합성: 특정 산업군(의료, 금융)의 용어나 법적 규제를 위반하지 않는지 검증하는 전용 데이터셋입니다.
ㄷ. 왜 필요 할까?
상호 운용성 (Interoperability): 모델을 교체하더라도 기존 앱이 문제없이 작동함을 보장
품질 보증 (QA): 최소한의 성능 마지노선을 설정하여 배포 전 리스크를 방지
컴플라이언스: 개인정보 보호나 윤리적 가이드라인을 시스템이 강제하고 있는지 확인
ㄹ. 관련 도구 및 라이브러리
LLM 평가에서 적합성 스위트 역할을 수행하는 대표적인 프레임워크들
Promptfoo: 다양한 프롬프트와 모델을 대상으로 대규모 적합성 테스트를 실행하고 시각화
Instructor / Pydantic: LLM의 출력이 특정 스키마(데이터 구조)에 적합한지 강제하고 검증
OpenAI Evals: OpenAI에서 공개한 프레임워크로, 모델의 성능이 특정 기준에 부합하는지 측정하는 테스트 스위트를 만들 수 있음
3. 스펙을 리포에 둔다는 말을 무슨 의미일까?
개발 실무에서 “스펙(Spec)을 리포(Repository)에 둔다”는 말은, 시스템이 지켜야 할 규칙이나 평가 기준을 문서 파일이나 코드 형태로 Git 저장소(GitHub, GitLab 등) 내에 직접 저장하여 관리한다는 뜻이며,
과거에는 스펙을 ‘노션’이나 ‘워드 문서’에 적어두고 눈으로 확인했다면, 이제는 “데이터와 코드로서 관리”하겠다는 철학이 담겨 있음
ㄱ. 구체적으로 무엇을 리포에 두는가?
LLM-as-a-Judge나 적합성 스위트 관점에서는 다음과 같은 파일들을 의미
평가 프롬프트 파일 (
judge_prompt.yaml): 어떤 기준으로 점수를 매길지 적어둔 프롬프트 원본
테스트 케이스 데이터셋 (test_cases.json): “질문 – 모범 답안 – 기대하는 평가 결과”가 담긴 데이터
스키마 정의 (schema.json또는 Pydantic 코드): LLM이 반드시 내뱉어야 하는 JSON 구조 정의
성능 하한선 (config.toml): “정확도 90% 미만이면 배포 금지”와 같은 임계값(Threshold)
ㄴ. 왜 리포에 두는 것일까?
- 버전 관리 (Versioning)
프롬프트를 수정했을 때 “누가, 언제, 왜” 고쳤는지 기록이 남습니다. 만약 평가 방식이 바뀌어 갑자기 점수가 낮아진다면,git diff를 통해 이전 스펙과 비교하고 롤백할 수 있음 - CI/CD 파이프라인 연동 (Automated Testing)
이게 가장 핵심, 개발자가 코드를 수정해서 리포에 올리면(Push), GitHub Actions 같은 도구가 리포에 있는 스펙 파일을 읽어서 자동으로 LLM 평가를 돌림
– 과정: 코드 수정 → 자동 평가 실행 → 리포에 정의된 스펙(90점 이상 등) 미달 시 → “배포 차단” - Single Source of Truth (단일 진실 공급원)
“어떤 게 최신 기준이지?”라고 물어볼 필요 없이, 리포에 있는 파일이 현재 시스템의 공식 스펙이 됩니다. 기획자와 개발자가 같은 파일을 보고 소통하게 됨
ㄷ. 예시 구조(폴더 구성)
ㄹ. 결론
“스펙을 리포에 둔다”는 것은“평가 기준을 코드화(Everything as Code)하여, 사람이 일일이 확인하지 않아도 시스템이 스스로 합격/불합격을 판단하게 만들겠다”*는 의지의 표현
4. 트레이스 로그(Trace Log)는 어떤 것일까?
하나의 요청(Request)이 시스템에 들어와서 처리가 끝날 때까지 어떤 경로를 거쳐갔는지 그 발자취를 시간순으로 기록한 데이터를 말함
단순히 “에러가 났다”는 기록(Error Log)이나 “누가 들어왔다”는 기록(Access Log)보다 훨씬 상세하며, 주로 여러 개의 서비스가 얽혀 있는 복잡한 시스템(마이크로서비스 아키텍처, MSA)에서 흐름을 파악하기 위해 사용
ㄱ. 트레이스 로그의 핵심 구성 요소 2가지
Trace ID (전체 경로 ID): 사용자가 버튼을 클릭한 순간부터 결과가 나올 때까지 발생하는 모든 과정에 부여되는 고유 번호입니다. 여러 서버를 거쳐도 이 ID는 동일하게 유지되어 전체 흐름을 하나로 묶어줌
Span ID (개별 작업 ID): 전체 경로 중 특정 구간(함수 호출, DB 쿼리 등)에서 발생하는 단위 작업의 ID입니다. 각 구간마다 얼마나 시간이 걸렸는지 측정함
ㄴ. 왜 트레이스 로그가 필요한가?
일반적인 로그만으로는 알 수 없는 문제들을 해결
- 병목 구간 찾기: “사용자 응답이 왜 이렇게 느리지?”라는 질문에 대해, “A 서버에서 0.1초, B 서버에서 2.5초, DB에서 0.5초 걸렸음”이라고 정확히 짚어줌
- 장애 원인 추적: 여러 서버가 연동된 경우, 어느 지점에서 연결이 끊겼는지 혹은 어떤 데이터가 전달되다가 에러가 났는지 흐름을 따라가며 확인할 수 있음
- 서비스 간 의존성 파악: 우리 시스템의 서비스들이 서로 어떻게 호출하고 응답하는지 지도로 그려낼 수 있음
ㄷ. LLM 서비스에서의 트레이스 로그
: LLM-as-a-Judge나 RAG 시스템에서도 트레이스 로그는 필수적
: 아래 과정을 트레이스 로그로 남겨두면, “왜 답변이 이상했지?”라고 분석할 때 검색된 문서가 문제였는지, LLM의 추론이 문제였는지를 로그 파일 하나로 다 확인할 수있다고 함
[사용자 질문 유입 (Trace Start)]
1. Step 1: 질문을 벡터로 변환 (Embedding Span – 0.2s)
2. Step 2: 벡터 DB에서 관련 문서 검색 (Retrieval Span – 0.5s)
3. Step 3: LLM에 프롬프트 전달 및 생성 (Generation Span – 2.0s)
4. 결과 반환 (Trace End)
ㄹ. 관련 도구 (Observability Tools)
트레이스 로그를 수집하고 시각화해주는 대표적인 도구들
OpenTelemetry: 로그를 수집하는 글로벌 표준 규격
Jaeger / Zipkin: 수집된 트레이스 로그를 타임라인 형태로 보여주는 시각화 도구
LangSmith / Arize Phoenix: LLM(LangChain 등) 흐름을 추적하는 데 특화된 전용 트레이싱 도구
5. 계층적 요약은 어떻게 하는 걸까?
ㄱ. 계층적 요약의 3단계 프로세스
1단계: 청킹 (Chunking)
먼저 긴 문서를 LLM이 한 번에 처리하기 적절한 크기(예: 2,000 ~ 4,000 토큰)로 잘게 나눔
* 단순히 글자 수로 자르기보다는 의미 단위(문단, 섹션)로 자르는 것이 품질에 좋다
2단계: 리프 노드 요약 (Leaf Node Summarization)
잘린 각 조각(Chunk)들을 LLM에 넣어 각각 개별 요약본을 만듭니다. 이를 ‘Map’ 단계라고도 부름
* 결과: 10개의 조각이 있었다면, 10개의 짧은 요약본이 생성
3단계: 재귀적 병합 (Recursive Merging)
생성된 요약본들을 다시 합쳐서 더 상위의 요약본을 만듭니다. 이 과정은 최종적으로 하나의 요약문이 나올 때까지 반복
* 예시: 10개의 요약본을 5개씩 묶어 2개의 요약본으로 만들고, 최종적으로 그 2개를 합쳐 1개의 최종 요약본 생성
ㄴ. 주요 전략 (Map-Reduce vs. Refine)
| 전략 | 작동 방식 | 장점 | 단점 |
| Map-Reduce | 각 조각을 병렬로 요약한 뒤 합침. | 속도가 매우 빠름 (병렬 처리 가능). | 조각 간의 문맥 연결이 어색할 수 있음. |
| Refine | 첫 조각 요약본을 다음 조각과 함께 넣어 수정해 나감. | 앞뒤 문맥 유지가 매우 잘 됨. | 순차적으로 진행되어 처리 속도가 느림. |
ㄷ. 왜 계층적 요약을 쓸까?
1. 정보 손실 최소화: 전체를 억지로 압축하는 것보다 세부 디테일을 단계별로 보존하며 요약할 수 있음
2. 비용 및 효율성: 모델의 최대 입력 한계를 넘어서는 초장문 데이터(논문 수백 편 등)를 처리할 수 있는 유일한 방법
3. 구조화된 이해: 요약 과정에서 만들어진 중간 단계의 요약본들을 통해 문서의 ‘목차’나 ‘구조’를 자동으로 파악할 수 있음
ㄹ. 구현 시 TIP
Overlap (중복 배치): 조각을 나눌 때 끝부분을 약간씩 겹치게 자르면(예: 10% 중복), 조각 사이의 정보가 끊기는 것을 방지할 수 있음
프롬프트 고정: 중간 단계 요약 시 “중요한 고유 명사와 수치는 반드시 포함하라”는 지침을 주어야 최종 요약에서 핵심 정보가 누락되지 않음
일단, 학습은 했지만 머리 속에 기억이 다 되는 것은 아니라 차근차근 기록 할 예정