소속팀: Developer팀 작성자: 유수영
🤖 모델을 바꿀 때마다 Agent 코드를 다시 고쳐야 할까요?
모델 연결과 업무 흐름의 책임을 나누면 변경할 범위를 줄일 수 있습니다. 다만 호출 방식이 같아졌다고 답변 품질과 지원 기능까지 같아지는 것은 아닙니다. 이 글은 공통 인터페이스와 제공자별 어댑터로 그 차이를 다루는 설계 사례입니다.
기존 설계의 중심은 AgentConfig, 팩터리, 등록소, 공통 모델 인터페이스입니다. 여기에 메시지 호환, 스트리밍, 토큰 예산, 장애 대응을 연결합니다. 코드는 설계 원리를 확인하는 축약 예제이며, 실제 제공자 SDK 구현은 아닙니다.
| 궁금한 점 | 이 글에서 살펴볼 내용 |
|---|---|
| 모델을 교체하면 왜 주변 코드도 바뀔까? | 인증·메시지·응답 형식의 차이 |
| 공통화는 어디까지 해야 할까? | 호출 계약과 기능 지원의 경계 |
| 답변이 나오다 끊기면 어떻게 할까? | 스트리밍의 완료·중단 구분 |
| 대체 모델로 바로 넘겨도 될까? | 실패 유형과 전환 조건 |
| 모델 교체를 어떻게 결정할까? | 품질·응답 시간·비용의 비교 |
1. 개요: 두 번째 모델을 연결할 때 보이는 차이
처음에는 모델 하나를 연결해 질문에 답하도록 만듭니다. 그다음 비용이나 배포 조건에 맞춰 다른 모델을 검토합니다. 업무 흐름은 같은데, 인증과 요청 옵션을 다시 맞춰야 합니다. 응답에서 본문을 꺼내는 코드까지 달라질 수 있습니다.
이 사례에서는 그런 차이를 제공자별 어댑터로 모았습니다. 서비스는 질문과 근거를 준비하고, 어댑터는 모델 호출을 담당합니다. 모델 선택은 설정과 생성 단계에서 결정합니다. 연결 방식이 업무 코드 곳곳으로 퍼지지 않도록 하는 구조입니다.
사용자에게 중요한 것은 어떤 SDK를 썼는지가 아닙니다. 질문에 맞는 답변이 오고, 실패했을 때 상태를 알 수 있어야 합니다. 모델을 바꾸더라도 이 약속은 유지할 필요가 있습니다. 공통 인터페이스는 그 약속을 코드로 표현하는 출발점입니다.
그림 1. 반복되는 연결은 공통화하고, 업무 판단은 Agent에 남깁니다. AI 생성 일러스트입니다.
제공자와 모델 이름은 같은 개념이 아니다
Azure OpenAI는 모델을 호출하는 관리형 서비스의 예입니다. GPT-OSS, Llama, Qwen은 모델 계열을 가리킵니다. 같은 모델 계열도 어떤 추론 서버로 배포하느냐에 따라 호출 방식이 달라집니다.
따라서 모델 이름 하나만으로 모든 호환성을 판단하지 않습니다. 모델, 배포 대상, API 방식, 지원 기능을 함께 확인합니다. 어떤 계열이 항상 더 싸거나 특정 업무에 더 낫다고 단정하지도 않습니다.
2. 상세내용: 공통 계약과 제공자별 차이를 나누기
2.1 업무 코드에서 분리할 차이들
| 달라지는 요소 | 서비스에 직접 넣었을 때의 문제 | 어댑터에서 처리할 일 |
|---|---|---|
| 인증과 접속 주소 | 환경마다 호출 코드 수정 | 승인된 연결 설정 적용 |
| 메시지 형식 | 역할과 본문 변환이 중복됨 | 제공자 요청 형식으로 변환 |
| 출력 제한 옵션 | 같은 설정 이름을 오해함 | 지원 옵션과 의미 검증 |
| 응답 본문 | 문자열·블록 처리 코드가 섞임 | 공통 응답 형식으로 변환 |
| 스트리밍 | 종료와 오류 처리 방식이 달라짐 | 이벤트 의미 통일 |
| 사용량·오류 | 비용과 장애 비교가 어려움 | 공통 기록 형식으로 정리 |
공통화한다고 제공자의 모든 차이를 숨기지는 않습니다. 지원하지 않는 기능은 시작 전에 알려야 합니다. 예를 들어 도구 호출이 필요한 업무에 텍스트 전용 모델을 연결하면 안 됩니다.
2.2 호출 흐름은 단순하게, 응답의 의미는 분명하게
기존 설계는 LLMModel과 제공자별 구현을 분리합니다. AgentFramework는 설정을 읽고 등록소나 팩터리에서 모델을 준비합니다. 업무 흐름은 준비된 모델을 호출합니다.

그림 2. 설정에 따른 선택은 시작 시점에, 요청·응답 변환은 어댑터에서 수행합니다.
응답을 무조건 str(response)로 바꾸는 방식은 피합니다. 도구 호출이나 구조화된 결과가 일반 답변처럼 표시될 수 있기 때문입니다. 본문, 종료 이유, 사용한 제공자, 사용량을 별도 필드로 다루는 편이 좋습니다.
아래 예제는 텍스트 답변만 다루는 최소 계약입니다. Python 3.10 이상과 표준 라이브러리로 실행할 수 있습니다. 실제 서비스에서는 도구 호출과 이미지 입력에 맞는 계약을 별도로 확장합니다.
|
from dataclasses import dataclass, field |
|---|
사용량이 제공되지 않으면 None을 유지합니다. 이를 0으로 채우면 사용하지 않은 것처럼 집계됩니다. 타입 주석만으로 외부 응답이 검증되는 것은 아니므로 어댑터 경계에서 검사합니다.
2.3 AgentConfig와 팩터리로 생성 책임 모으기
AgentConfig는 어떤 연결을 사용할지 선언합니다. 팩터리는 그 이름에 맞는 생성 함수를 선택합니다. 등록하지 않은 이름을 기본 모델로 조용히 바꾸지 않습니다.
|
@dataclass(frozen=True) |
|---|
기존 등록소가 있다면 같은 생성 책임을 두 곳에 중복해서 만들 필요는 없습니다. 등록소에 팩터리를 연결하거나, 한쪽으로 역할을 모을 수 있습니다. 중요한 것은 서비스가 제공자 생성 코드를 직접 반복하지 않는 것입니다.
실제 연결에서는 클라이언트를 재사용할 범위도 정합니다. 서비스가 만든 연결은 종료 시 정리하고, 요청별 대화 상태는 따로 보관합니다. 동시에 호출할 수 있는지는 사용하는 클라이언트의 계약을 확인합니다.
2.4 작은 대역으로 모델 교체 흐름 확인하기
외부 연결 없이 생성과 호출 계약을 확인할 수 있는 대역을 준비합니다. 아래 두 이름은 제공자 전환을 설명하기 위한 가상 설정입니다. 실제 모델의 성능이나 지원 기능을 나타내지는 않습니다.
|
class SampleModel: |
|---|
model_type을 바꾸면 다른 생성 함수를 선택합니다. 대역은 옵션 전달을 확인할 뿐 실제 토큰 제한이나 타임아웃을 실행하지 않습니다. 운영 어댑터는 옵션을 SDK에 매핑하고, 실제 동작도 검증해야 합니다.
💡 팩터리가 모델을 만들었다는 사실과 업무에 쓸 준비가 됐다는 판단은 다릅니다. 인증, 기능 지원, 출력 형식, 대표 질문의 품질을 다음 단계에서 확인합니다.
2.5 메시지 호환: 역할과 내용 블록을 함께 보기
기존 설계는 일부 모델을 LangChain의 BaseChatModel과 호환되도록 다룹니다. 업무에서는 SystemMessage, HumanMessage 같은 메시지를 유지할 수 있습니다. 하지만 모든 제공자의 결과가 문자열 하나인 것은 아닙니다.
LangChain 메시지 문서는 문자열과 내용 블록을 구분합니다. 본문 외에 이미지, 도구 호출, 사용량 같은 정보가 함께 있을 수 있습니다. 어댑터는 서비스가 지원하는 형식으로 변환하고, 처리할 수 없는 값은 명시적으로 거부합니다.
| 메시지의 요소 | 유지해야 할 의미 |
|---|---|
| 역할 | 시스템 지시, 사용자 질문, 도구 결과 구분 |
| 본문 | 사용자에게 전달할 텍스트와 다른 블록 구분 |
| 도구 호출 | 호출 ID, 이름, 인자, 실행 결과의 연결 |
| 종료 이유 | 정상 완료, 길이 제한, 거절, 다음 도구 호출 구분 |
| 사용량 | 입력·출력·추가 세부 정보의 출처 보존 |
LangGraph의 노드는 업무 단계와 상태를 연결합니다. 공통 어댑터는 해당 노드가 사용할 모델 연결을 준비합니다. 상태와 실행 흐름의 역할은 LangGraph 공식 개요를 참고할 수 있습니다.
2.6 프롬프트와 제공자 설정을 따로 관리하기
프롬프트에는 업무 의도와 답변 기준을 담습니다. 제공자 설정에는 인증, 접속 대상, 모델 연결 정보를 담습니다. 둘을 한곳에 섞으면 모델 연결을 바꾸는 일과 업무 정책을 바꾸는 일이 얽힙니다. 변경 이유를 나누어 관리할 수 있어야 합니다.
예를 들어 “근거가 부족하면 부족하다고 안내한다”는 업무 정책입니다. 어느 모델 서비스에 접속할지는 연결 설정입니다. 출력 한도와 시간 제한은 실행 옵션입니다. 담당 영역이 다르면 검토할 항목도 달라집니다.
그렇다고 프롬프트가 모든 모델에서 같은 결과를 낸다고 가정하지는 않습니다. 같은 메시지를 보내도 지시를 따르는 방식이나 출력 길이가 달라질 수 있습니다. 업무 기준은 유지하면서 대표 질문으로 결과를 비교합니다. 필요한 조정은 변경 이력과 평가 결과를 함께 남깁니다.
그림 3. 연결은 바꾸되 업무에서 기대하는 답변 계약은 유지합니다. AI 생성 일러스트입니다.
| 영역 | 관리할 내용 | 검토할 질문 |
|---|---|---|
| 업무 프롬프트 | 답변 기준, 예시, 근거 사용 정책 | 상담 의도에 맞는가? |
| 제공자 설정 | 접속 주소, 배포 대상, 인증 | 허용된 연결인가? |
| 실행 옵션 | 출력 한도, 시간 제한, 지원 옵션 | 모델이 같은 의미로 처리하는가? |
| 운영 기록 | 지연, 사용량, 종료 이유 | 변경 전후를 비교할 수 있는가? |
모든 모델이 temperature 같은 옵션을 지원하는 것은 아닙니다. 지원 여부와 허용 범위는 선택한 모델·API에서 확인합니다. 지원하지 않는 값을 몰래 무시하기보다 설정 검증 단계에서 알려줍니다.
2.7 업무 서비스에는 질문과 근거를 남기기
아래 서비스는 앞에서 만든 공통 모델을 받습니다. 검색 근거는 이미 사용자의 접근 권한에 맞게 선택됐다고 가정합니다. 실제 검색과 권한 검사는 이 코드의 범위 밖입니다.
|
import json |
|---|
응답 객체를 유지하면 본문과 종료 이유를 함께 처리할 수 있습니다. 화면은 정상 답변인지, 제한으로 잘렸는지 구분해 표시합니다. 프롬프트의 지시만으로 답변 정확성이 보장되지는 않으므로 평가가 필요합니다.
2.8 스트리밍: 마지막 조각과 정상 완료는 다르다
스트리밍은 답변이 만들어지는 동안 일부 내용을 먼저 보여주는 방식입니다. 제공자마다 본문 조각, 사용량, 종료 이벤트의 형식이 다릅니다. 연결이 끝났다는 이유만으로 정상 완료를 보내면 중간 장애를 숨길 수 있습니다.
OpenAI의 스트리밍도 이벤트 종류에 따라 의미가 나뉩니다. 구체적인 형식은 공식 스트리밍 문서를 참고할 수 있습니다. 아래 코드는 제공자 이벤트를 이미 공통 형식으로 변환한 뒤의 처리 예제입니다.
|
class ProviderFailure(RuntimeError): |
|---|
이 예제는 정상 종료 신호를 받아야 done을 보냅니다. 길이 제한은 incomplete로, 생성 거절은 refusal로 구분합니다. 도구 호출과 비동기 취소를 다루는 서비스는 해당 상태도 별도로 확장해야 합니다.
사용자가 화면을 닫으면 소비하는 쪽에서도 스트림을 닫아야 합니다. 최종 답변을 저장할 때는 완료·중단 상태를 함께 기록합니다. 부분 답변을 정상 답변으로 재사용하거나 대화 이력에 확정해서는 안 됩니다.
2.9 토큰 예산: 글자 수로 자르면 무엇을 놓칠까?
기존 예제의 문자 수 제한은 긴 입력을 줄이는 간단한 방법입니다. 하지만 문자 수와 토큰 수는 같지 않습니다. 중간에서 자르면 중요한 제외 조건이나 문서 출처가 사라질 수도 있습니다.
입력 예산에서는 시스템 지시, 질문, 대화 이력, 도구 정의까지 고려합니다. 출력에 쓸 한도와 여유분도 남겨야 합니다. 일부 모델의 출력 한도에는 화면에 보이지 않는 토큰도 포함됩니다. 이 차이는 OpenAI 토큰 계산 문서에서 확인할 수 있습니다.
아래 코드는 문서 묶음을 통째로 선택하는 예제입니다. count_tokens는 실제 모델의 메시지 형식까지 반영하는 계산 함수라고 가정합니다. 대표 문서와 제외 조건 첨부처럼 함께 필요한 내용은 하나의 묶음으로 전달합니다.
|
def build_messages(system_prompt, question, context_groups, *, count_tokens, |
|---|
검색 순위 순서로 묶음을 검토하고, 들어갈 수 있는 묶음을 선택합니다. 큰 묶음 하나가 빠져도 뒤의 작은 묶음은 포함될 수 있습니다. 실제 서비스에서는 선택·제외한 근거 ID와 이유도 기록합니다.
🧩 예산에 맞췄다는 것이 답변 근거가 충분하다는 뜻은 아닙니다. 필수 문서가 제외됐다면 추가 검색이나 답변 보류를 검토합니다. 토큰 계산이 추정치라면 여유분을 두고 실제 사용량과의 차이를 점검합니다.
2.10 오류를 나누고 재시도 책임은 한곳으로
| 오류 유형 | 대응 방향 | 주의할 점 |
|---|---|---|
| 인증·권한 오류 | 설정과 접근 범위 수정 | 같은 요청을 반복해도 해결되지 않음 |
| 입력 초과·지원하지 않는 옵션 | 입력·설정 검증 | 모델을 바꿔 오류를 숨기지 않음 |
| 일시적인 연결 실패 | 제한된 재시도 검토 | 남은 시간과 중복 실행 고려 |
| 호출량 제한 | 안내된 대기 조건과 호출량 조정 | 한꺼번에 재호출하지 않음 |
| 생성 거절 | 별도 종료 상태로 처리 | 거절을 우회하려고 다른 모델 호출 금지 |
| 본문 전송 후 스트림 실패 | 부분 응답과 실패 안내 | 다른 모델 답변을 이어 붙이지 않음 |
SDK와 서비스가 각각 재시도하면 실제 시도 횟수가 크게 늘 수 있습니다. 재시도 횟수, 대기 간격, 전체 시간 한도를 한곳에서 관리합니다. 요청마다 같은 간격으로 몰리지 않도록 대기 시간을 분산할 수 있습니다.
시간 초과가 곧 제공자 측 실행 취소를 뜻하지는 않습니다. 도구 실행이나 외부 저장이 포함된 요청은 중복 실행 여부도 확인해야 합니다. 사용자 취소와 서버의 실패도 운영 기록에서 구분합니다.
2.11 대체 모델은 승인된 조건에서만 사용하기
대체 모델을 쓰는 fallback은 장애 대응의 한 방법입니다. 하지만 사내 전용 데이터를 외부 모델로 보내는 경로가 되어서는 안 됩니다. 데이터 취급, 지원 기능, 답변 품질을 확인한 조합만 허용합니다.

그림 4. 재시도와 모델 전환은 오류 종류, 출력 상태, 업무 정책을 확인한 뒤 결정합니다.
다음은 비스트리밍 텍스트 생성에서 대체 경로를 설명하는 예제입니다. 도구 실행 같은 외부 변경이 없고, 본문을 아직 사용자에게 보내지 않았다고 가정합니다. allowed는 앞서 확인한 전환 정책의 결과이며, 자동 승인 값이 아닙니다.
|
from dataclasses import replace |
|---|
실제 운영에서는 남은 시간과 최대 시도 횟수도 전달해야 합니다. 대체 호출까지 실패하면 성공 응답으로 바꾸지 않고 오류를 전달합니다. 사용한 모델과 전환 이유는 기록하고, 대체 응답도 품질 평가에 포함합니다.
2.12 제공자 비교는 업무 조건과 실제 결과로
| 선택지 | 먼저 확인할 항목 | 비교할 결과 |
|---|---|---|
| Azure OpenAI 등 관리형 서비스 | 배포 대상, 인증, API 지원 범위 | 품질, 지연, 호출 제한, 비용 |
| 사내 추론 서버 | 지원 모델, 메시지 형식, 운영 자원 | 같은 조건의 품질과 운영 안정성 |
| GPT-OSS·Llama·Qwen 등 모델 계열 | 선택한 모델 버전과 배포 방식 | 업무 평가셋에서의 결과 |
| 테스트 대역 | 고정 응답과 실패 재현 | 연결 계약과 오류 처리 |
표의 항목은 성능 순위가 아닙니다. 모델 계열과 제공 방식이 겹칠 수 있으므로 실제 배포 조합으로 비교합니다. API 형식이 호환돼도 도구 호출, 내용 블록, 사용량까지 같은지 따로 확인합니다.
관리형 연결은 Microsoft 공식 문서를 참고할 수 있습니다. 호환 메시지 API의 사례는 Hugging Face TGI Messages API에서 확인할 수 있습니다. 적용 여부는 사용 중인 서버와 모델의 지원 범위를 기준으로 판단합니다.
2.13 운영 기록: 요청한 모델과 실제 사용 모델 구분하기
대체 모델이 정상 답변을 만들면 사용자 화면에서는 장애가 보이지 않을 수 있습니다. 운영에서는 원래 연결의 실패가 계속 늘고 있을 수 있습니다. 최종 성공 여부만 기록하면 그 변화를 놓치기 쉽습니다. 요청 단위 결과와 호출 시도별 기록을 함께 봐야 합니다.
사용량도 최종 응답만 더하면 실제 비용과 차이가 생깁니다. 실패한 시도나 재시도에서 사용량이 발생했을 수 있기 때문입니다. 제공자가 보고한 값과 추정한 값을 구분해 보관합니다. 사용량을 받지 못한 경우도 별도 상태로 남깁니다.
모델 교체는 품질과 시간, 비용을 함께 비교하는 결정입니다. 같은 문서와 질문을 사용하고 프롬프트·옵션 버전도 기록합니다. 평균에 가려진 중요한 질문의 실패나 긴 지연이 없는지도 확인합니다. 새 모델을 연결할 수 있다는 사실만으로 운영 전환을 결정하지 않습니다.
그림 5. 실제 호출 모델과 실패·전환 이력을 함께 점검합니다. AI 생성 일러스트입니다.
| 기록 항목 | 확인하려는 질문 |
|---|---|
| 요청 ID·시도 번호 | 재시도와 최종 요청 결과를 연결할 수 있는가? |
| 요청 모델·실제 모델 | 대체 경로가 사용됐는가? |
| 입력·출력 사용량 | 측정값인가, 추정값인가, 누락됐는가? |
| 첫 응답·전체 응답 시간 | 사용자가 언제 답변을 보기 시작했는가? |
| 종료 이유·오류 유형 | 완료, 제한, 거절, 장애가 구분되는가? |
| 설정·프롬프트 버전 | 품질 변화의 조건을 재현할 수 있는가? |
p95는 측정 요청의 약 95%가 그 값 이하에 해당하는 지연 기준입니다. 평균 지연과 함께 오류율, 전환율, 요청당 사용량을 봅니다. 품질은 대표 질문의 근거 충실성, 조건 누락, 응답 형식으로 따로 평가합니다.
2.14 대역 테스트와 실제 제공자 검증을 나누기
대역으로는 설정 전달, 응답 계약, 실패 경로를 빠르게 확인합니다. 실제 제공자에서는 인증, 옵션 적용, 스트림 이벤트, 사용량을 확인합니다. 대역의 고정 답변으로 실제 모델 품질을 평가할 수는 없습니다.
|
def test_interrupted_stream_never_reports_done(): |
|---|
✅ 정상 호출 외에도 지원하지 않는 옵션, 출력 제한, 취소, 부분 실패를 포함합니다. 실제 모델을 교체할 때는 같은 평가셋으로 답변과 근거를 다시 비교합니다. 서비스에 필요한 기능 하나라도 빠졌다면 연결 성공과 별개로 전환을 보류합니다.
3. 결론: 모델을 숨기기보다 변경할 경계를 만들기
LLM 제공자 추상화는 연결 차이를 한곳에서 관리하는 방법입니다. 설정과 팩터리로 모델을 선택하고, 공통 계약으로 메시지와 응답을 주고받습니다. 업무 흐름은 질문, 근거, 답변 기준에 집중할 수 있습니다.
운영에서는 정상 답변 외의 상태가 더 중요해질 때가 있습니다. 출력이 잘렸는지, 중간에 끊겼는지, 대체 모델을 사용했는지까지 표현해야 합니다. 공통화의 완성도는 이런 차이를 정확히 전달하는지에서도 드러납니다.
🚀 처음에는 텍스트 호출 한 가지부터 공통화해 볼 수 있습니다. 그다음 필요한 기능과 실패 상태를 추가하고, 테스트와 평가로 계약을 확인합니다. 모델 교체를 작은 변경으로 만들되, 품질 확인까지 생략하지 않는 것이 이 설계의 목표입니다.
4. 참조 출처
제공자별 형식과 메시지 동작은 아래 공식 문서를 참고했습니다. 예제의 모델 이름과 응답은 설명용이며 실제 성능 측정 결과가 아닙니다.
- OpenAI — Streaming API Responses: 스트리밍 응답과 이벤트 처리.
- OpenAI — Counting Tokens: 입력·출력 토큰과 한도 해석.
- Microsoft — Foundry Documentation: 관리형 모델과 Agent 관련 문서.
- LangChain — Models: 공통 모델 호출과 기능.
- LangChain — Messages: 메시지 역할과 내용 블록.
- LangGraph — Overview: 상태와 실행 흐름 구성.
- Hugging Face — TGI Messages API: 호환 메시지 API의 예.
일러스트 세 장은 AI로 생성한 설명용 이미지입니다. 흐름도 두 개는 직접 작성했으며 편집 가능한 draw.io 원본을 함께 보관합니다. 실제 서비스 화면이나 운영 결과를 촬영한 이미지는 아닙니다.
5. 태그
#LLM #AIAgent #ModelAbstraction #FactoryPattern #AzureOpenAI #GPTOSS #Llama #Qwen #LangChain #LangGraph #Python #Streaming #모델교체 #장애대응