🚀 기술 브리핑: 이 튜토리얼은 Gate of AI의 에이전트 워크플로우(Agentic Workflows) 심층 분석 시리즈 중 일부입니다. 전체 기술 분석, 인터랙티브 코드 샌드박스 및 네이티브 아랍어 번역을 보려면 원문 기사 바로가기를 방문하십시오.

튜토리얼
중급

Qdrant FastAPI RAG API: 근거 기반 서비스 구축하기

Qdrant 시맨틱 검색, BAAI/bge-m3 임베딩, FastAPI, LangChain 오케스트레이션, GPT-5 생성 및 Pydantic 응답 유효성 검사를 사용하여 검색 증강 생성(RAG) API를 구축합니다.

이 Qdrant FastAPI RAG API가 구축하는 것

검색 증강 생성(Retrieval-Augmented Generation), 즉 RAG는 언어 모델을 외부 지식 컬렉션에 연결합니다. 애플리케이션이 모델에게 학습된 매개변수만으로 답변하도록 요청하는 대신, 먼저 관련 구절을 검색한 다음 해당 구절들을 생성 단계에 제공합니다. Qdrant는 이 아키텍처에서 벡터 검색 계층을 제공합니다. FastAPI가 애플리케이션 엔드포인트를 노출하고, LangChain이 검색 및 생성 워크플로우를 조정할 수 있습니다.

본 튜토리얼은 검증된 컨텍스트에 문서화된 컴포넌트 패턴을 따릅니다: 시맨틱 검색을 위한 Qdrant, 다국어 임베딩을 위한 BAAI/bge-m3, 백엔드 API를 위한 FastAPI, 생성을 위한 GPT-5 또는 GPT-5-mini, 그리고 구조적 유효성 검사를 위한 Pydantic입니다. 문서화된 RAGTIME 구현은 15개의 상위 청크(top chunks)를 검색하고 생성 전에 약 5~7개의 문서를 재구성합니다. 이 값들은 모든 코퍼스에 대한 보편적인 설정이 아니라 재현 가능한 기준선으로 사용됩니다.

이 설계는 연구 자료, 법률 문서, 기관 지식, 다국어 정보원과 같은 도메인 컬렉션에 유용합니다. 검증된 컨텍스트에서 법률 리서치 예시는 Qdrant, FastAPI, 그리고 React 프런트엔드를 결합합니다. 또 다른 기록된 시스템은 개인정보 보호에 중점을 둔 어시스턴트의 장기적인 의미론적 저장소로 Qdrant를 사용합니다. 이러한 예시들은 아키텍처 패턴을 보여줄 뿐이며, 모든 Qdrant 배포가 동일한 정확도, 지연 시간 또는 개인정보 보호 속성을 제공한다는 것을 증명하지는 않습니다.

RAG API는 네 가지 개념적 단계를 거칩니다. 첫째, 문서는 구절(passages)로 분할됩니다. 둘째, 임베딩 모델이 이 구절들을 벡터로 변환합니다. 셋째, Qdrant가 질문 벡터에 가까운 구절을 검색합니다. 넷째, 언어 모델이 검색된 증거를 바탕으로 답변을 생성합니다. 이 답변은 선택된 컨텍스트의 종합물로 취급되어야 하며, 진실의 자동적인 보증으로 여겨서는 안 됩니다.

아키텍처 및 검증된 설계 선택

요청 경로는 의도적으로 간단합니다:

• 문서 준비: 원본 자료가 정리되고 검색 구절로 분할됩니다.
• 임베딩: BAAI/bge-m3는 구절과 질문을 다국어 의미론적 검색에 적합한 벡터로 변환합니다.
• 벡터 검색: Qdrant가 질문 벡터와 가장 가까운 구절들을 반환합니다.
• 컨텍스트 조립: 서비스는 가장 강력한 증거를 선택하고 관리 가능한 문서 컨텍스트를 재구성합니다.
• 생성: GPT-5 또는 GPT-5-mini가 질문과 검색된 증거를 받습니다.
• 스키마 검증: Pydantic이 API 응답을 검증하고 JSON 형태의 계약(contract)을 강제할 수 있습니다.

의미 검색(Semantic retrieval)은 일반적인 키워드 조회와 다릅니다. 벡터 검색 시스템은 의미의 수치적 표현을 비교하기 때문에, 질문과 지문이 같은 단어를 공유하지 않아도 일치할 수 있습니다. 이는 특히 다국어 컬렉션과 도메인 언어에 중요합니다. 그러나 의미적 유사성이 곧 그 지문이 질문에 답한다는 것을 보장하지는 않습니다. 따라서 검색 품질은 대표적인 쿼리(query)와 예상되는 출처 문서로 평가되어야 합니다.

검증된 RAGTIME 예제는 의도적으로 간결한 아키텍처를 사용합니다: Qdrant, BAAI/bge-m3, FastAPI, GPT-5 또는 GPT-5-mini, 그리고 Pydantic JSON 스키마 강제 적용. 이 예제는 인용 기반의 JSON 보고서를 생성하는 파이프라인을 보고합니다. 중요한 교훈은 이 정확한 스택(stack)이 항상 최적이라는 것이 아니라, 검색(retrieval), 생성(generation), 검증(validation) 사이에 작고 명확하게 정의된 인터페이스가 불필요하게 복잡한 시스템보다 검사하기 쉽다는 것입니다.

1단계: Python 프로젝트 준비

Python 프로젝트를 생성하고 구현에 필요한 라이브러리를 설치합니다. 아래의 버전 범위는 의도적으로 보수적인 예시입니다. 배포 전에 선택한 버전들을 자체 환경에서 함께 테스트하십시오. 검증된 컨텍스트는 FastAPI, Qdrant, LangChain, BAAI/bge-m3, GPT-5 계열 생성(generation), Pydantic의 역할을 확립하지만, 보편적인 패키지 잠금 파일(package lockfile)이나 호스팅 구성을 확립하지는 않습니다.

mkdir qdrant-fastapi-rag
cd qdrant-fastapi-rag
python -m venv .venv
...

문서는 documents라는 디렉토리에 배치합니다. 처리할 권한이 있는 자료를 사용하십시오. 다국어 평가의 경우, 사용자들이 쿼리할 언어의 문서를 포함해야 합니다. BAAI/bge-m3가 선택된 이유는 검증된 컨텍스트에서 이 모델을 다국어 RAG 시스템의 임베딩 모델로 식별했기 때문입니다.

소스 파일에 자격 증명(credentials)을 넣는 대신 환경 변수(environment variables)를 통해 구성을 정의하십시오:

검증된 출처는 특정 Qdrant 호스팅 방식, 포트, 인증 체계 또는 배포 토폴로지를 확립하지 않습니다. 사용자가 선택한 Qdrant 환경에서 필요한 연결 설정을 사용하십시오. 벡터 스토어와 생성 제공자를 분리하여 구성하면 두 구성 요소 각각을 독립적으로 평가할 수 있습니다.

2단계: 인제스천 및 검색 서비스 생성

app/main.py 파일을 만드십시오. 이 간결한 서비스는 BAAI/bge-m3를 로드하고, 모델의 벡터 크기를 사용하여 Qdrant 컬렉션을 생성하며, 일반 텍스트 파일을 색인화하고, 질문당 15개의 구절을 검색하며, GPT-5 계열 모델에게 구조화된 응답 생성을 요청합니다. 이 코드는 생성을 위해 최신 OpenAI 클라이언트 구성을 사용합니다. 생성 제공자 구성은 환경에서 선택한 모델을 지원해야 합니다.

import os
from pathlib import Path
from typing import Any
...

예제는 검증된 RAGTIME 구성과 일치하도록 의도적으로 15개의 청크를 검색합니다. 더 많은 수가 자동으로 더 좋지는 않습니다: 관련 없는 구절은 생성기에게 제공되는 증거를 희석시킬 수 있습니다. 또한, 검증된 구현은 여러 청크가 동일한 출처에 속할 때 유용한 개선 사항인 약 5~7개의 문서를 재구성합니다. 해당 동작을 재현하려면 검색된 페이로드를 source 필드별로 그룹화하고, 원본 위치별로 청크를 정렬하며, 생성 전에 재구성되는 문서 수를 제한하십시오.

3단계: 문서 색인 및 API 실행

서비스를 시작하고 색인 엔드포인트를 호출합니다:

uvicorn app.main:app --host 127.0.0.1 --port 8000

curl -X POST http://127.0.0.1:8000/v1/index
...

응답에는 답변과 검색된 출처가 포함됩니다. 두 필드를 모두 검사하세요. 예상 문서가 출처에 없는 경우, 실패는 문서 준비, 임베딩 또는 검색에 있습니다. 올바른 출처는 존재하지만 답변이 틀린 경우, 컨텍스트 조립(context assembly), 생성 지침 및 스키마 처리를 조사해야 합니다. 검색 평가와 생성 평가를 분리하는 것은 RAG 프로젝트에서 가장 중요한 디버깅 관행 중 하나입니다.

구조화된 보고를 위해 AskResponse를 짧은 답변, 인용 목록 및 증거 상태(evidence-status) 값과 같은 필드로 확장하세요. Pydantic은 반환되는 객체가 클라이언트에 도달하기 전에 예상된 형태를 가지고 있는지 검증할 수 있습니다. 검증된 RAGTIME 시스템은 유효한 구조화된 출력을 강제하기 위해 특히 Pydantic JSON Schema를 사용하므로, 스키마 검증을 미적인 API 기능이라기보다는 파이프라인의 일부로 다루어야 합니다.

4단계: 검색 및 근거 기반 평가(Evaluate Retrieval and Grounding)

질문, 예상 출처 문서 및 답변 요구 사항을 포함하는 작은 평가 세트를 만드세요. 예상 출처가 상위 15개 결과 중 나타나는지, 재구성된 컨텍스트에 필요한 구절이 포함되어 있는지, 그리고 생성된 답변이 적절한 출처를 인용하는지 측정하세요. 컬렉션에서 답변할 수 없는 질문도 포함해야 합니다. 근거 기반 시스템은 지원되지 않는 내용으로 공백을 채우기보다는 충분한 증거가 부족함을 나타낼 수 있어야 합니다.

다국어 질문은 별도로 평가하세요. BAAI/bge-m3는 다국어 의미 검색(multilingual semantic search)에 대해 검증된 컨텍스트에 문서화되어 있지만, 사용자와 관련된 언어, 용어 및 문서 형식에 대해서도 여전히 다국어 기능을 테스트해야 합니다. 한 언어로 된 질문이 다른 언어로 작성된 관련 구절을 검색하는지 확인하고, 모든 도메인에서 교차 언어 검색이 동일하게 강력하다고 가정하기보다는 실패 사례를 기록하세요.

어떤 실험의 결과를 보편적인 정확도 약속으로 변환해서는 안 됩니다. 검증된 연구 보고서는 특정 코퍼스 및 모델 설정에서 구체적인 결과들을 제시합니다. 여기에는 소형 Gemma 모델을 평가한 연구와 인용 기반 리포트를 위해 설계된 TREC 시스템이 포함됩니다. 이러한 발견들은 아키텍처의 타당성을 뒷받침할 뿐, 사용자 본인의 문서에 대한 보장된 점수를 의미하지는 않습니다.

한계점 및 프로덕션 고려 사항

RAG는 외부 증거를 제공함으로써 지원되지 않는 생성을 줄일 수 있지만, 환각(hallucination)을 완전히 제거하지는 못합니다. Qdrant가 의미론적으로 가깝지만 충분하지 않은 구절을 검색할 수도 있습니다. 언어 모델은 상충되는 구절을 잘못 읽거나 잘못된 증거를 인용할 수 있습니다. 또한 원본 자료 자체가 불완전하거나, 합성적이거나, 오래되었거나, 특정 전문 영역에 한정적일 수 있습니다. 이러한 한계점들은 합성 개인 데이터, 코퍼스 커버리지, 그리고 일부 설정에서의 환각 행동과 관련된 제약 사항을 언급한 검증된 연구와 관련하여 명시적으로 중요합니다.

접근 통제(Access control)는 예제를 넘어선 설계가 필요합니다. 해당 코드는 검색 및 생성을 시연할 뿐, 테넌트 격리(tenant isolation), 신원 관리(identity management), 법적 준수(legal compliance), 또는 완전한 개인 정보 보호 프로그램은 확립하지 못합니다. 민감한 자료를 인덱싱하기 전에, 어떤 데이터가 각 구성 요소로 전송될 수 있는지, 얼마나 오래 보관되는지, 누가 검색할 수 있는지, 그리고 출처 수준의 권한이 어떻게 적용될지 결정해야 합니다. 이러한 사항들을 Qdrant나 FastAPI만으로 암시되는 기능이 아니라 배포 요구사항(deployment requirements)으로 간주하십시오.

더 큰 컬렉션의 경우, 각 Qdrant 페이로드에 문서 식별자(document identifiers), 청크 위치(chunk positions), 언어 메타데이터(language metadata), 그리고 버전 정보를 추가해야 합니다. 그런 다음 초기 의미 검색에 사용했던 것과 동일한 규율로 필터링된 검색 및 라이프사이클 작업(lifecycle operations)을 평가하십시오. 만약 애플리케이션이 다국어 또는 법률 사용자들을 대상으로 한다면, 사용자들이 응답 뒤의 증거를 검사할 수 있도록 원본 출처 텍스트와 인용 메타데이터를 보존해야 합니다.

핵심 요약

• Qdrant는 검증된 RAG 아키텍처의 벡터 검색(vector retrieval) 구성 요소입니다.
• FastAPI가 API 경계(API boundary)를 제공하며, LangChain은 검색 및 생성 워크플로우를 오케스트레이션할 수 있습니다.
• BAAI/bge-m3는 문서화된 RAGTIME 시스템에서 검증된 다국어 임베딩(multilingual embedding) 선택지입니다.
• GPT-5와 GPT-5-mini는 해당 시스템에서 설명하는 검증된 생성 옵션입니다.
• 15개의 청크를 검색하고 5~7개의 문서를 재구성하는 것은 평가를 위한 문서화된 기준선(baseline)을 제공합니다.
• Pydantic JSON Schema는 예측 가능하며 인용 기반의 응답 계약(citation-oriented response contract)을 강제하는 데 도움을 줍니다.
• 검색 품질, 증거 커버리지(evidence coverage), 그리고 거부 행동(abstention behavior)은 목표 코퍼스에서 측정되어야 합니다.

출처 및 검증 노트 (Sources and Verification Notes)

이 튜토리얼은 Gate of AI 에디토리얼 및 엔지니어링 팀에 제공되는 검증된 컨텍스트를 기반으로 업데이트되었습니다. 주요 참고 자료들은 Qdrant, FastAPI, LangChain, BAAI/bge-m3, GPT-5 계열 생성(GPT-5-family generation), Pydantic 스키마 강제 적용(Pydantic schema enforcement), 다국어 RAG, 그리고 도메인별 애플리케이션을 설명합니다. 아키텍처 및 연구 결과는 프로덕션 도입 전에 독자 자신의 환경에서 재현하고 평가되어야 합니다.