🚀 기술 브리핑: 이 튜토리얼은 Gate of AI의 에이전트 워크플로우(Agentic Workflows) 심층 분석 시리즈 중 일부입니다. 전체 기술 분석, 상호작용 코드 샌드박스 및 네이티브 아랍어 번역을 보려면 원문 기사 바로가기를 방문하십시오.
튜토리얼 · 중급
FastAPI를 사용한 프롬프트 계약 서비스 구축하기
버전 관리되는 프롬프트 계약(prompt contract)과 OpenAI Structured Outputs를 중심으로 FastAPI 서비스를 설계하는 방법을 배웁니다. 핵심 원칙은 스키마가 답변의 형태를 제약한다는 것이며, 애플리케이션은 여전히 그 의미를 확인하고, 거부 및 불완전한 응답을 처리하며, 요청된 모든 작업을 승인해야 합니다.
프롬프트 계약 서비스란 무엇인가요?
기존의 API 계약은 애플리케이션이 수락하는 입력과 출력을 설명합니다. 프롬프트 계약은 유사한 아이디어를 AI 모델의 런타임 동작에 적용합니다: 이는 작업을 설명하고, 관련 컨텍스트를 제공하며, 허용되는 응답 형태와 모델이 따라야 할 경계를 정의합니다. 시스템 프롬프트를 단지 문서로 취급하는 대신, 이 접근 방식은 이를 AI 인터페이스의 한 구성 요소로 간주합니다.
이것은 프롬프트가 백엔드를 대체할 수 있다는 주장이 아니라 아키텍처적 실험입니다. 실제 서비스는 여전히 요청을 받고, 입력을 검증하며, 데이터베이스 및 외부 서비스에 연결하고, 어떤 작업이 허용되는지 결정하는 애플리케이션 코드가 필요합니다. 유용한 사고 모델은 기존 시스템 위에 놓인 계층입니다: 사용자 요청이 API에 도착하고, LLM 런타임이 이를 해석하며, 애플리케이션 코드가 결과로 나오는 구조화된 작업이 진행될 수 있는지 여부를 결정합니다.
이 튜토리얼은 지원 티켓 라우팅(support-ticket routing)을 실행 예시로 사용합니다. 서비스는 모델에게 티켓을 허용된 레이블 세트로 분류하도록 요청하고 구조화된 결과를 반환할 수 있습니다. 이 모델의 결과가 워크플로우에 정보를 제공할 수는 있지만, 그 자체가 선택된 레이블이 정확하다는 증거는 아닙니다. 또한 구조화된 결과가 환불 처리, 계정 변경 또는 다른 결과적인 작업을 수행할 권한을 의미하지도 않습니다.
전제 조건 및 범위 (Prerequisites and Scope)
- Python, HTTP API, JSON, 그리고 FastAPI 개념에 대한 숙지.
- 서비스를 OpenAI와 연결하려는 경우 OpenAI API 계정.
- 명확하게 정의된 사용 사례(use case), 제한된 허용 레이블 세트, 그리고 오류 검토 계획.
제공되는 자료는 여기에 설명된 아키텍처와 안전성 구분을 확립하지만, 특정 SDK 버전, 모델 이름, 가격 책정 또는 복사-실행 통합을 검증하지는 않습니다. 해당 세부 정보에 대해서는 배포 전에 최신 공식 API 및 프레임워크 문서를 참조하십시오. 아래 단계들은 테스트된 미검증의 제공업체별 코드를 제시하는 대신, 서비스 경계를 구축하고 그 책임을 정의하는 데 중점을 둡니다.
1단계: 애플리케이션 계약 정의 (Define the Application Contract)
애플리케이션의 실제 필요성부터 시작하십시오. “고객을 이해한다”와 같은 모호한 목표는 피해야 합니다. 대신, “제공된 티켓에 근거하여 이 승인된 세트에서 하나의 레이블을 선택하고 간략한 설명을 제공하라”와 같이 경계가 정해진 작업(bounded task)을 작성하십시오. 어떤 입력 필드가 필요한지, 그리고 다운스트림 애플리케이션이 안전하게 소비할 수 있는 출력 필드는 무엇인지 결정해야 합니다.
라우팅 서비스의 경우, 요청 계약에는 티켓 식별자와 고객 메시지가 포함될 수 있습니다. 응답 계약에는 라우트 레이블, 간략한 근거(rationale), 그리고 검토 지표가 포함될 수 있습니다. 승인된 레이블은 모델이 임의로 만들어내는 것이 아니라 애플리케이션에 의해 정의되어야 합니다. 유효한 목적지가 몇 개밖에 없다면, 이를 출력 스키마에서 명시적인 열거형(enumeration)으로 표현해야 합니다.
모든 필드의 목적을 문서화해야 합니다. '근거(rationale)'는 운영자에게 제공하는 설명일 뿐, 선택된 경로가 정확하다는 보장이 아닙니다. '검토 지표(review indicator)'는 애플리케이션 로직이 별도로 정의한 효과를 부여하지 않는 한 추천에 불과합니다. 모델이 가지지 않은 권한을 암시하는 필드(예: 결제 실행 또는 계정 변경 지침)는 피해야 합니다.
백엔드 시스템이 권한을 갖도록 유지해야 합니다. 백엔드는 어떤 서비스에 접근 가능한지, 어떤 작업이 허용되는지, 그리고 인간 또는 다른 승인 프로세스가 필요한지를 결정해야 합니다. 프롬프트는 작업을 설명하고 원하는 결과를 제시할 수 있지만, 자체적으로 권한을 설정하거나 작업을 합법화할 수는 없습니다.
2단계: 버전 관리되는 프롬프트 계약 작성 (Write a Versioned Prompt Contract)
시스템 프롬프트를 유지 관리되는 애플리케이션 아티팩트(application artifact)로 작성해야 합니다. 작업을 명시하고, 완료하는 데 필요한 컨텍스트만 제공하며, 허용된 레이블 목록을 나열하고, 출력 기대치를 설명해야 합니다. 팀이 특정 결정과 해당 결정을 생성하는 데 사용된 프롬프트 버전을 연결할 수 있도록 애플리케이션 구성 또는 기록에 프롬프트 버전 식별자(version identifier)를 부여해야 합니다.
정책 지침(policy instructions)은 사용자 제공 콘텐츠와 분리하여 유지해야 합니다. 티켓은 서비스 계약을 변경할 권한의 원천이 아니라 입력 데이터입니다. 모델에게 작업을 위해 티켓을 어떻게 처리해야 하는지 알려주되, 악성 또는 관련 없는 콘텐츠를 무력화하기 위해 그 지침에만 의존해서는 안 됩니다. 주변 애플리케이션은 여전히 응답을 검증하고 다음에 발생할 수 있는 것을 제한해야 합니다.
평가할 수 있는 지침을 작성해야 합니다. 예를 들어, 모델이 문서화된 레이블 세트에서 하나의 항목을 선택하고 스키마(schema)가 요구하는 필드를 반환하도록 명시해야 합니다. 프롬프트가 모든 오류나 프롬프트 주입(prompt-injection) 시도를 방지할 것이라고 약속하는 것을 피하십시오. 프롬프트는 모델의 동작을 안내할 뿐이며, 애플리케이션 제어(application controls)의 필요성을 제거하지 않습니다.
변경 사항을 의도적으로 유지하세요. 태스크(task), 레이블(labels) 또는 출력 필드(output fields)가 변경될 때마다 계약(contract)을 업데이트하고 소비자에게 미치는 영향을 평가해야 합니다. 프롬프트의 변화는 JSON 구조가 변하지 않더라도 필드의 의미를 바꿀 수 있습니다. 버전 관리(Versioning)는 이러한 행동적 변화를 조사 및 평가에서 식별하기 쉽게 만듭니다.
3단계: 구조화된 출력 스키마 정의 (Define a Structured Output Schema)
호출자(caller)가 지정된 스키마를 준수하는 응답이 필요할 때 구조화된 출력(Structured Outputs)을 사용합니다. 스키마는 필드 이름, 유형(type), 그리고 구성된 경우 열거형(enumeration)의 허용 가능한 값을 제한할 수 있습니다. 이는 라우팅 인터페이스에 유용한데, 응답이 문서화되지 않은 레이블을 임의로 만들거나 임의의 필드를 추가하는 것을 방지할 수 있기 때문입니다.
이 보장(guarantee)을 정확성(correctness)과 혼동하지 마십시오. 스키마가 네 개의 라우트 레이블을 허용하더라도, 모델은 티켓에 여전히 틀린 구조적으로 유효한 레이블을 반환할 수 있습니다. 스키마 준수(Schema adherence)는 형식(form)에 대한 질문에 답하는 것이지, 선택된 값이 사실적 또는 운영적으로 적절함을 확립하지 않습니다.
스키마는 모델이 말할 수 있는 모든 것을 중심으로 설계하는 것이 아니라, 다운스트림 애플리케이션(downstream application)을 중심으로 설계해야 합니다. 필드는 명시적(explicit)으로 만들고 적절한 경우 자유 형식 텍스트(free-form text)를 제한합니다. 서비스가 모델의 결과를 받아들일 수 없을 때 어떻게 응답할지 결정해야 합니다. 특히, 거부(refusals) 및 불완전한 응답을 성공적인 분류로 취급하기보다는 별개의 결과(distinct outcomes)로 처리하십시오.
FastAPI 측면에서는, HTTP 경계(HTTP boundary)에서 들어오는 요청을 검증하고 다른 애플리케이션 구성 요소에 전달하기 전에 수락된 모델 결과를 검증해야 합니다. 현재 OpenAI SDK를 FastAPI에 연결하는 정확한 코드는 지원되는 API 및 라이브러리 버전에 따라 다르므로, 최신 공식 문서를 통해 확인하십시오. 임의의 텍스트를 성공적인 구조화된 응답으로 조용히 파싱(silently parse)하지 마십시오.
4단계: 모델 요청과 애플리케이션 실행 분리 (Separate Model Requests from Application Execution)
서비스는 책임 영역별로 구성되어야 합니다. HTTP 계층은 요청을 받아 응답을 반환합니다. 모델 통합 계층(model-integration layer)은 태스크와 스키마를 제공자에게 보내고 사용 가능한 결과를 받았는지 보고합니다. 정책 계층(policy layer)은 애플리케이션 규칙과 비교하여 결과를 확인합니다. 실행 계층(execution layer)은 필요한 경우, 해당 검사가 완료된 후에만 승인된 백엔드 서비스를 호출합니다.
이러한 분리는 특히 함수 호출(function calling)을 사용할 때 중요합니다. 모델이 생성한 함수 호출은 애플리케이션이 작업을 수행하도록 제안하는 요청입니다. 이는 호출자가 권한을 가지고 있다는 증거, 요청된 작업이 안전하다는 증거, 또는 해당 작업이 실행되어야 한다는 증거가 아닙니다. 애플리케이션 코드는 함수를 실행하기 전에 인수를 검증하고 권한 부여(authorization)를 적용해야 합니다.
예를 들어, 모델은 고객 계정과 관련된 작업을 제안할 수 있습니다. 백엔드는 독립적으로 해당 계정이 존재하는지, 호출자가 그 계정에 대해 행동할 권한이 있는지, 현재 규칙에 따라 작업이 허용되는지, 그리고 추가적인 승인이 필요한지를 확인해야 합니다. “권한을 가진 작업만 수행하라”는 프롬프트가 이러한 검사를 대체할 수 없습니다.
권한 및 결정론적 요구사항(deterministic requirements)은 코드와 권위 있는 데이터(authoritative data)에 유지해야 합니다. 정확한 접근 규칙, 승인 요건 및 기타 협상 불가능한 조건들은 모델이 프롬프트를 해석하는 것에 위임되어서는 안 됩니다. 모델은 정보 추출이나 분류를 돕는 데 사용할 수 있지만, 해당 정보가 무엇을 허용하는지 결정하는 것은 애플리케이션의 책임으로 남습니다.
Step 5: 거부(Refusals), 불완전한 결과 및 오류 처리
서비스는 완전하고 사용 가능한 구조화된 결과와 거부 응답(refusal), 불완전한 응답, 제공자 오류(provider error), 또는 애플리케이션 유효성 검사에 실패한 응답을 구별해야 합니다. 검증된 가이드는 특히 구현체가 처리해야 하는 사례로 거부 및 불완전한 응답을 명시적으로 언급합니다. 이 모든 것을 일반적인 JSON 결과로 취급하면 호출자에게 모호한 동작을 초래합니다.
엔드포인트를 워크플로우에 연결하기 전에 명시적인 실패 정책(failure policy)을 정의해야 합니다. 사용 사례에 따라 서비스는 제어된 오류를 반환하거나, 추가 검토를 요청하거나, 항목을 사람에게 보낼 수 있습니다. 모든 실패를 기본 경로로 조용히 매핑해서는 안 됩니다. 그렇게 하면 이용할 수 없거나 응답하지 않는 모델이 유효한 결정을 내린 것처럼 보이게 할 수 있기 때문입니다.
오류 메시지는 API 소비자에게 적합하도록 유지하고, 비밀 정보나 내부 구현 세부 사항을 노출하는 것을 피해야 합니다. 실패 원인을 조사하기에 충분한 운영 정보를 기록하되, 고객 콘텐츠를 불필요하게 수집하는 것은 피해야 합니다. 실패 경로는 운영자에게는 눈에 보여야 하고 클라이언트에게는 예측 가능해야 합니다.
응답이 사용 가능한 경우, 먼저 그 구조(structure)를 검증하고 그다음 애플리케이션 규칙에 비추어 의미(meaning)를 평가해야 합니다. 이들은 별개의 확인 절차입니다. 응답은 스키마 유효성 검사(schema validation)를 통과하더라도 여전히 비즈니스 규칙을 위반할 수 있습니다. 애플리케이션은 제품이 정의한 정책에 따라 해당 경우를 거부하거나, 에스컬레이션 처리하거나, 달리 처리해야 합니다.
6단계: FastAPI를 통해 계약 노출하기(Expose the Contract Through FastAPI)
요청 모델을 받아들이고 문서화된 응답 모델을 반환하는 FastAPI 엔드포인트를 생성합니다. HTTP 경로는 간결하게 유지해야 합니다. 이 경로는 들어오는 형태(shape)를 검증하고, 서비스 계층(service layer)을 호출하며, 그 정의된 결과들을 처리한 후, 적절한 결과를 반환하는 역할을 해야 합니다. 정책, 제공업체 통합(provider integration), 실행 로직을 하나의 큰 라우트 핸들러에 넣는 것을 피해야 합니다.
이 엔드포인트가 무엇을 하는지, 그리고 무엇을 하지 않는지를 문서화해야 합니다. 만약 추천 경로를 반환한다면, 그것을 '추천'이라고 부르십시오. 애플리케이션이 실제로 필요한 승인(authorization) 및 실행 단계를 수행하지 않았다면, 이를 권한 있는 조치로 묘사해서는 안 됩니다. 사용자 제공 프롬프트나 정책을 신뢰할 수 있는 서비스 구성처럼 받아들이지 마십시오.
엔드포인트를 게시하기 전에, 누가 호출할 수 있는지 그리고 어떤 백엔드 기능에 접근할 수 있는지 결정해야 합니다. 인증(Authentication), 권한 부여(Authorization), 요청 제한(request limits), 운영 제어(operational controls)는 애플리케이션의 책임이며, 구조화된 출력 스키마로는 제공되지 않습니다. 제공된 자료들은 특정 FastAPI 배포 구성을 규정하지 않으므로, 서비스를 실행할 환경과 비교하여 해당 세부 사항을 확인하십시오.
클라이언트가 의존할 수 있는 관점에서 서비스 계약을 문서화해야 합니다: 허용되는 입력(accepted input), 가능한 성공적인 출력(possible successful outputs), 그리고 거부(refusal), 불완전한 출력(incomplete output), 유효성 검사 실패(validation failure), 또는 사용 불가 상위 서비스(unavailable upstream service)에 대한 동작 방식입니다. 가능하다면 공개 계약을 안정적으로 유지하고, 소비자에게 영향을 미치는 의도적인 변경 사항은 버전을 지정해야 합니다.
7단계: JSON뿐만 아니라 결정(Decision)까지 평가하기
중요한 워크플로우에서 서비스를 사용하기 전에 대표적인 평가 세트(evaluation set)를 구축하십시오. 일반적인 예시, 모호한 사례, 그리고 잘못된 분류가 중요할 수 있는 사례들을 포함해야 합니다. 각 사례에 대해, 애플리케이션이 신경 쓰는 레이블과 안전 결정(safety decisions)의 관점에서 예상되는 동작을 정의합니다.
스키마와 결정을 분리하여 테스트하십시오. 스키마 테스트는 필수 필드와 허용된 값이 존중되는지 확인합니다. 결정 테스트는 선택된 레이블과 모든 에스컬레이션 권장 사항이 해당 예시에 적절한지 확인합니다. 첫 번째 범주의 테스트를 통과했다고 해서 두 번째 범주까지 통과했다는 의미는 아닙니다.