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

<span class="Tutorial">튜토리얼</span>
<span class="Intermediate">중급</span>
<span class="⏱ 25 min read">읽는 시간 25분</span>
...

LangChain Gemini 파일 검색 RAG API 구축하기

Gemini API File Search를 중심으로 관리형 검색(managed retrieval), 의미론적 문서 검색(semantic document search), 자동 인용, 명확한 비용 모델을 갖춘 접지된(grounded) RAG 워크플로우 설계 방법을 알아봅니다.

이 튜토리얼에서 구축하는 것

검색 증강 생성(Retrieval-Augmented Generation), 일반적으로 RAG라고 불리는 것은 생성형 모델을 통제된 문서 컬렉션에 연결합니다. 애플리케이션이 단순히 일반적인 학습 지식만으로 모델에게 답변하도록 요청하는 대신, 관련 자료를 검색하여 그 자료를 응답의 컨텍스트로 제공합니다. 그 결과는 더 관련성이 높고, 검증하기 쉬우며, 조직 자체 문서와 더 잘 정렬될 수 있습니다.

이 워크플로우에 대한 검증된 Gemini API 경로는 File Search입니다. 이는 Gemini API에 내장된 완전 관리형 RAG 시스템입니다. File Search는 파일 저장소, 청킹(chunking), 임베딩(embeddings), 벡터 검색(vector search) 및 검색된 컨텍스트를 프롬프트에 동적으로 주입하는 과정을 관리합니다. 이는 로컬 Chroma 스토리지를 제안하고 애플리케이션 소유의 수집(ingestion) 논리를 사용했던 원래 초안의 자체 관리형 아키텍처와는 실질적으로 다릅니다.

이 튜토리얼은 검증되지 않은 패키지 코드를 프로덕션 레디 상태로 제시하지 않으면서 LangChain과 Gemini를 활용한 RAG 애플리케이션을 계획하는 방법을 설명합니다. 사용 가능한 기술 컨텍스트는 LangChain과 Gemini가 RAG 프로젝트에서 함께 사용된다는 점을 확인하지만, 특정 현재의 LangChain 통합 패키지, 메서드 시그니처 또는 종속성 버전을 검증하지는 않습니다. 이러한 이유로 본 가이드에서 검증된 구현 경계는 Gemini API의 기존 generateContent API와 그 파일 검색(File Search) 기능입니다.

완성된 디자인은 네 가지 논리적 단계로 구성됩니다. 첫째, 승인된 문서가 파일 검색 지식 소스에 추가됩니다. 둘째, Gemini의 관리 시스템이 검색을 위해 자료를 준비합니다. 셋째, 사용자 질문이 인덱싱된 콘텐츠와 의미적으로 매칭됩니다. 넷째, 검색된 컨텍스트는 답변 생성을 위해 Gemini에 제공되며, 사용된 문서 자료를 식별하는 인용(citation)이 포함됩니다. 애플리케이션 계층은 오케스트레이션을 위해 LangChain을 사용할 수 있지만, 그렇게 해야 할 검증된 요구사항이 없는 한 관리되는 검색 구성 요소를 중복해서는 안 됩니다.

RAG에 Gemini API 파일 검색을 사용해야 하는 이유?

전통적인 RAG 구현은 일반적으로 여러 독립적으로 구성된 서비스나 라이브러리를 필요로 합니다. 팀은 파일 저장소(file store)를 선택하고, 텍스트를 추출하며, 문서를 어떻게 분할할지 결정하고, 임베딩을 생성하고, 벡터를 영속화하며, 유사성 검색을 실행하고, 프롬프트를 구성하고, 출처 참조를 보존해야 합니다. 각 경계는 설정 및 유지보수 작업을 도입합니다. 또한 답변 품질을 저하시킬 수 있는 인덱싱 버그가 발생할 수 있는 장소를 더 많이 만듭니다.

파일 검색은 이 파이프라인을 간소화합니다. 검증된 Google 발표에 따르면, 이는 파일 저장, 최적의 청크 분할 전략(chunking strategies), 임베딩, 그리고 검색된 컨텍스트를 프롬프트에 동적으로 주입하는 것을 자동으로 관리합니다. 이 기능은 기존 generateContent API 내에서 작동하므로, 애플리케이션은 문서 검색을 근거로 추가하면서 동일한 생성 워크플로우를 사용할 수 있습니다.

검색(Retrieval)은 정확한 단어 일치에만 의존하는 것이 아니라 의미론적입니다. File Search는 Gemini Embedding 모델이 제공하는 벡터 검색을 사용하여 질의의 의미와 맥락을 파악합니다. 이는 질문의 표현 방식이 원본 문서와 다를 때 중요합니다. 예를 들어, 사용자가 “고객 장애 에스컬레이션(customer outage escalation)”에 대해 문의할 수 있지만, 색인된 정책은 “서비스 중단 대응(service disruption response)”이라는 구문을 사용할 수 있습니다. 의미론적 검색(Semantic search)은 이러한 관련 개념들을 연결할 수 있습니다.

File Search는 또한 내장된 인용(citation) 기능을 제공합니다. 응답은 답변을 생성하는 데 사용된 색인 문서의 어느 부분이였는지 자동으로 식별합니다. 이러한 참조 정보는 지원팀, 기술 문서 포털, 내부 정책 비서, 그리고 연구 워크플로우에 중요합니다. 왜냐하면 사용자가 생성된 산문(prose)을 자체적으로 유효하다고 취급하기보다는 증거를 검사할 수 있기 때문입니다.

필수 조건 및 범위

• Gemini API에 접근할 수 있는 Google AI Studio 또는 Google Cloud 환경.
• 질문에 답변하는 데 사용하도록 권한이 부여된 문서들.
• API 요청, JSON, 프롬프트(prompt), 그리고 환경 기반 설정에 대한 기본적인 이해.
• Gemini API를 호출하고 그 결과를 사용자나 다운스트림 서비스에 노출할 수 있는 애플리케이션 계층.
• 선택적으로, 문서(documents), 검색기(retrievers), 프롬프트, 모델 오케스트레이션과 같은 LangChain 개념에 대한 이해.

검증된 컨텍스트는 현재의 LangChain 패키지 버전이나 검증된 File Search 어댑터 API를 제공하지 않습니다. 가져오기 이름이 익숙해 보인다는 이유만으로 오래된 통합 예제를 프로덕션 프로젝트에 복사하지 마십시오. 패키지나 메서드 시그니처를 선택하기 전에 최신 LangChain 공급자 문서와 최신 Gemini API 문서를 확인하십시오.

비밀번호, API 키, 액세스 토큰, 기밀 내보내기 파일 또는 애플리케이션이 검색할 수 없어야 하는 문서는 업로드하지 마십시오. RAG 시스템은 인덱싱된 콘텐츠 주변에 구현된 경계를 존중할 수 있을 뿐입니다. File Search는 검색을 개선하지만, 그 자체로 조직의 권한 정책을 정의하는 것은 아닙니다.

1단계: 지식 컬렉션 정의하기

먼저 애플리케이션이 답변하도록 허용되는 내용이 무엇인지 정확히 결정하는 것부터 시작하십시오. 폭넓게 필터링되지 않은 아카이브보다 좁고 잘 관리된 컬렉션이 일반적으로 더 유용합니다. 적절한 출처에는 제품 매뉴얼, 승인된 지원 문서, 내부 절차, 기술 참고 자료 또는 정책 문서가 포함될 수 있습니다. 올바른 출처 세트는 애플리케이션에 따라 다르지만, 모든 파일은 소유자와 포함 이유를 가져야 합니다.

파일을 업로드하기 전에 짧은 지식 범위(knowledge-scope) 문서를 작성하십시오. 이 문서에는 다음 다섯 가지 질문에 답해야 합니다: 누가 질문할 수 있는가? 어떤 문서가 범위 내에 있는가? 오래된 파일은 어떻게 제거되는가? 증거가 없을 때 어시스턴트는 무엇이라고 말해야 하는가? 부정확하거나 오해의 소지가 있는 답변은 누가 검토하는가? 이 질문들은 GCC 및 더 넓은 중동 지역에서 고객과 직원을 대상으로 서비스를 제공하는 팀을 포함하여 여러 부서나 언어에 걸쳐 운영되는 조직에게 특히 유용합니다.

다른 권한 수준들을 구별할 수 있도록 유지하십시오. 현재 승인된 정책이 오래된 프레젠테이션, 비공식적인 논의 또는 검증되지 않은 초안과 검토 없이 혼합되어서는 안 됩니다. 여러 버전이 필요한 경우, 출처 컬렉션에서 명확하게 레이블을 지정하고 애플리케이션이 충돌을 어떻게 처리해야 하는지 정의하십시오. 검색은 관련 텍스트를 찾을 수 있지만, 거버넌스가 어떤 출처를 신뢰해야 할지 결정합니다.

읽기 쉬운 제목, 완전한 문장 및 설명적인 파일 이름을 가진 문서들을 준비하십시오. 출처 형식의 품질이 낮으면 의미론적 일치(semantic match)가 정확하더라도 검색된 구절을 사용자가 이해하기 어렵게 만들 수 있습니다. 규칙, 정의, 예외 또는 절차를 해석하는 데 필요한 주변 맥락을 보존하십시오.

2단계: Gemini API 접근 설정

승인된 Google 환경에서 API 자격 증명을 생성하고, 이를 보호된 비밀 메커니즘을 통해 서버에 제공해야 합니다. 자격 증명을 브라우저 코드, 공개 저장소, 스크린샷 또는 실제 키와 유사한 튜토리얼 예제에 절대 포함하지 마십시오. 자격 증명은 Gemini를 호출하는 서버나 신뢰할 수 있는 서비스 내에 보관하십시오.

이 단계에서는 애플리케이션을 세 가지 개념적 값으로 설정해야 합니다: API 자격 증명, 현재 API 워크플로우에서 사용되는 파일 검색(File Search) 지식 소스 식별자, 그리고 해당 사용 사례에 대해 승인된 생성 설정입니다. 정확한 요청 필드와 SDK 메서드 이름은 반드시 최신 Gemini API 문서를 참조해야 합니다. 이는 본 감사용으로 제공된 검증된 컨텍스트에는 포함되어 있지 않기 때문입니다.

제공자(provider) 구성은 비즈니스 로직과 분리하여 유지하십시오. LangChain 애플리케이션은 오케스트레이션 계층을 사용하여 사용자 질문, 검색 단계, 프롬프트 및 생성된 답변을 표현할 수 있습니다. 하지만 파일 검색은 검증된 검색 권한으로 남아 있어야 합니다. 문서화된 이유가 있고 해당 구성 요소를 독립적으로 검증하지 않는 한, 두 번째 임베딩 모델, 로컬 벡터 데이터베이스 또는 애플리케이션 소유의 청킹 파이프라인을 추가하는 것을 피하십시오.

3단계: 파일 검색에 문서 추가하기

1단계에서 승인된 문서만 업로드해야 합니다. 파일 검색은 파일 저장소, 청킹, 임베딩 및 벡터 검색을 포함한 검색 파이프라인을 관리하도록 설계되었습니다. 이는 애플리케이션이 의미론적 문서 검색을 얻기 위해 별도의 로컬 데이터베이스에 해당 단계를 재현할 필요가 없다는 것을 의미합니다.

문서를 추가한 후에는 내부 인덱스 목록(inventory)을 기록해야 합니다. 이 목록에는 원본 파일 이름, 비즈니스 소유자, 추가 날짜, 언어, 개정 식별자 및 적용 가능한 경우 제거 날짜가 포함되어야 합니다. 이러한 필드는 팀을 위한 거버넌스 기록이므로, 파일 검색에 의해 자동으로 반환되는 메타데이터 필드에 대한 주장과 혼동해서는 안 됩니다.

원본 자료에 명확하게 존재하는 답변을 가진 직접적인 질문으로 컬렉션을 테스트하세요. 그런 다음 다른 용어를 사용하는 의역된 질문을 테스트합니다. 두 번째 그룹은 검증된 시스템의 벡터 검색이 정확한 단어보다는 의미와 맥락을 이해하도록 설계되었기 때문에 중요합니다.

또한 답변할 수 없는 질문도 테스트해야 합니다. 근거 기반 애플리케이션(grounded application)은 관련 증거가 없을 때 문서가 주장을 뒷받침한다고 암시해서는 안 됩니다. 애플리케이션 프롬프트와 사용자 경험에서 원하는 폴백 문구(fallback wording)를 정의하세요. 정확한 응답은 제품별로 다를 수 있지만, 증거의 경계를 명확히 해야 합니다.

4단계: 근거 기반 generateContent 요청 전송

파일 검색(File Search)은 Gemini의 기존 generateContent API 내에서 작동합니다. 애플리케이션의 요청에는 사용자의 질문과 현재 API 문서에서 요구하는 파일 검색 구성이 포함되어야 합니다. 그런 다음 모델은 관리된 검색 결과(managed retrieval result)를 컨텍스트로 사용하여 답변을 생성합니다.

답변의 증거 경계를 정의하는 프롬프트를 사용하세요. 실용적인 지침은 모델에게 검색된 문서에서 답변하도록, 해당 문서에 없는 사실을 꾸며내지 않도록, 충분한 증거가 부족함을 인정하도록, 그리고 중요한 한정 사항(qualifications)을 보존하도록 지시해야 합니다. 또한 애플리케이션이 응답 처리 중에 API가 반환하는 인용(citations)을 폐기하지 않고 유지하도록 지시해야 합니다.

인용을 장식적인 링크로 설명해서는 안 됩니다. 그것들은 검증 워크플로우의 일부입니다. 사용자는 어떤 원본 자료가 응답에 영향을 미쳤는지 식별할 수 있어야 합니다. 지원 인터페이스에서는 인용이 답변 옆에 나타날 수 있습니다. 내부 API에서는 다운스트림 인터페이스를 위해 구조화된 응답 데이터로 반환될 수 있습니다. 정확한 응답 형태는 현재 Gemini API 응답 계약(response contract)에 따라 달라지므로 공식 문서를 참고하여 구현해야 합니다.

LangChain을 사용하는 경우, File Search를 재구축하기보다는 검증된 워크플로우에 그 단계를 매핑해야 합니다. 개념적인 체인은 다음과 같습니다: 질문을 받고, File Search를 사용하여 Gemini 요청을 구성하며, generateContent를 호출하고, 생성된 답변을 추출하며, 반환된 인용(citation)을 보존하고, 최종적으로 답변과 증거(evidence)를 모두 호출자에게 반환합니다. 제공된 컨텍스트가 현재 LangChain 어댑터를 검증하지 않으므로, 일반적인 리트리버 클래스나 구형 Gemini 통합이 자동으로 File Search를 지원한다고 가정해서는 안 됩니다.

5단계: 검색 및 인용(Citation) 검증

튜토리얼을 완료하기 전에 작은 평가 세트를 만드세요. 직접 질문, 의역된 질문, 자격 조건이 필요한 질문, 컬렉션에 답변이 없는 질문, 그리고 두 개의 관련 문서를 결합하는 질문을 포함해야 합니다. 모든 테스트에 대해 검색된 증거가 관련성이 있는지, 답변이 뒷받침되는지, 인용이 검토자가 기대할 만한 자료를 식별하는지 기록하세요.

초기 개발 중에는 인용을 수동으로 검사하세요. 자동 인용은 검증 과정을 단순화하지만, 출처 품질 검토의 필요성을 제거하지는 않습니다. 답변이 문법적으로 명확하더라도 여전히 구식이거나 모호한 문서에 의존할 수 있습니다. 검토자는 응답과 인용된 출처를 비교하여 중요한 조건이 누락되었는지 기록해야 합니다.