이번 달 한 LLM 벤더가 두 개의 샘플링 파라미터 (sampling parameters)를 삭제했습니다. 해당 파라미터들을 전달하던 모든 하드코딩된 호출(hard-coded call)에서 에러가 발생하기 시작했습니다. 모델은 멀쩡했습니다. 가중치 (weights)도 멀쩡했습니다. 문제는 '계약 (contract)'이 변경되었다는 점입니다. 그리고 수천 개의 파이프라인은 자신들에게 그런 계약이 전혀 없었다는 사실을 깨달았습니다.

여기 불편한 대칭성이 있습니다. 여러분은 패키지 (packages) 버전을 고정합니다. API에 대해 계약 테스트 (contract-test)를 수행합니다. 카나리 (canary) 배포를 통해 잡아내지 않고서는 결제 제공업체가 요청 스키마 (request schema)를 변경하도록 내버려 두지 않을 것입니다. 하지만 여러분의 가장 눈에 띄는 기능의 중심에 자리 잡고 있는 LLM 호출은, 수동으로 조립되고 아무런 검증도 받지 않으며 오직 운영 환경 (production)에서만 테스트되는, 가공되지 않은 키워드 인자 (kwargs) 딕셔너리 (dict)일 뿐입니다.

여러분의 LLM도 하나의 의존성 (dependency)입니다. 의존성처럼 취급하세요. 지루하지만 중요한 세 가지 습관을 소개합니다:

1. 40개의 호출 지점이 아닌, 하나의 초크 포인트 (choke point)

# llm_client.py — 벤더와 통신하는 저장소 내 유일한 파일.
PINNED_MODEL = "vendor-model-2026-06-01"   # 날짜가 지정된 스냅샷, 절대 "latest"를 사용하지 말 것

...

파라미터가 사라졌을 때, 초크 포인트 (choke point)를 가진 팀은 단 한 줄의 수정으로 배포를 완료했습니다. 반면 40개의 파일에 키워드 인자 (kwargs)가 흩어져 있던 팀은 하루 종일 grep 명령어로 코드를 뒤져야 했습니다.

2. 운영 환경이 아닌 CI에서 실패하는 계약 테스트 (contract test)

# test_llm_contract.py — 모든 배포 시 및 야간 스케줄에 따라 실행됨
import jsonschema
from llm_client import build_request
...

$ pytest test_llm_contract.py -q
..                                                    [100%]
2 passed in 1.84s

3. 스냅샷을 고정하고, 업그레이드를 계획하라

모델 문자열에 포함된 "latest"는 요구 사항 파일 (requirements file)의 >=와 똑같은 거짓말입니다. 이는 "운영 환경에서 나를 놀라게 해달라"는 뜻과 같습니다. 날짜가 지정된 스냅샷을 고정하고, 업그레이드를 의도적인 이벤트로 만드세요. 새로운 스냅샷에 대해 골든 평가 (golden evals)를 실행하고, 출력값의 차이 (diff)를 비교한 다음, 고정된 버전을 변경하십시오. 이는 벤더의 스케줄이 아닌, 여러분의 캘린더에 따라 이루어져야 합니다.

이 중 새로운 엔지니어링은 없습니다. 여러분이 다른 모든 의존성 (dependency)에 이미 적용하고 있는 것과 동일한 규율입니다. 유일하게 새로운 점은 LLM 또한 의존성 중 하나임을 인정하는 것뿐입니다.

저는 Vinicius Fagundes입니다. 상파울루에서 수석 데이터 엔지니어 (principal data engineer), 독립 컨설턴트, 그리고 MBA 강사로 활동하고 있습니다. 저는 vf-insights.com을 통해 데이터 파이프라인(data pipelines)과 이를 평온하게 유지하는 관행(practices)에 대해 글을 씁니다.