Mastra와 Elasticsearch로 에이전틱 AI 애플리케이션을 구축하는 방법

이 글에서는 Mastra TypeScript 프레임워크를 사용해 Elasticsearch와 상호 작용하는 에이전틱 애플리케이션을 구축하는 방법을 자세히 살펴보겠습니다.

Elastic은 최근에 Elasticsearch를 벡터 데이터베이스로 지원하도록 추가하여 mastra-ai/mastra 오픈 소스 프로젝트에 기여했습니다. 이 새로운 기능을 통해 Mastra에서 Elasticsearch를 네이티브로 사용하여 임베딩을 저장할 수 있습니다. 벡터 기능 외에도 Elasticsearch는 컨텍스트 엔지니어링 요구 사항을 충족하기 위한 다양한 고급 기능을 제공합니다. (예: 하이브리드 검색 및 순위 재지정)

이 글에서는 Elasticsearch를 사용하여 Retrieval-Augmented Generation(RAG) 아키텍처를 구현하는 에이전트 생성 과정을 자세히 설명합니다. Elasticsearch에 저장된 SF 영화 데이터 코퍼스와 상호 작용하는 에이전틱 접근법을 사용하는 데모 프로젝트를 선보일 것입니다. 이 프로젝트는 elastic/mastra-elasticsearch-example에서 확인할 수 있습니다.

Mastra

Mastra는 에이전틱 AI 애플리케이션을 생성하기 위한 TypeScript 프레임워크입니다.

Mastra의 프로젝트 구조는 다음과 같습니다:

Mastra에서는 에이전트, 도구, 워크플로우 및 점수를 구축할 수 있습니다.

에이전트는 메시지를 입력으로 받아들이고 응답을 출력으로 생성하는 클래스입니다. 에이전트는 도구, 대형 언어 모델 (LLM), 메모리를 사용할 수 있습니다(그림 1).

에이전트의 도구를 사용하면 웹 API와 통신하거나 Elasticsearch 쿼리와 같은 내부 작업을 수행하는 등 '외부 세계'와 상호 작용할 수 있습니다. 메모리 구성 요소는 과거 입력과 출력을 포함하여 대화 기록을 저장하는 데 중요한 역할을 합니다. 이렇게 저장된 컨텍스트를 통해 에이전트는 과거 상호 작용을 활용하여 향후 질문에 대해 더 정보에 입각하고 정확도 높은 응답을 제공할 수 있습니다.

워크플로우를 사용하면 단일 에이전트의 추론에 의존하는 대신 명확하고 구조화된 단계를 통해 복잡한 작업 순서를 정의할 수 있습니다(그림 2). 이를 통해 작업을 어떻게 세분화하는지, 데이터가 작업 간에 어떻게 이동하는지, 그리고 언제 무엇이 실행되는지를 완벽하게 제어할 수 있습니다. 워크플로우는 기본적으로 내장된 실행 엔진을 사용하여 실행되거나 워크플로우 러너에 배포할 수 있습니다.

Mastra에서는 모델 등급, 규칙 기반 및 통계적 방법을 사용하여 에이전트 출력을 평가하는 자동화된 테스트인 점수를 정의할 수 있습니다. 채점기는 점수를 반환합니다. 이 점수는 출력물이 평가 기준을 얼마나 잘 충족하는지를 정량화한 수치 값(일반적으로 0에서 1 사이)입니다. 이러한 점수를 통해 성능을 객관적으로 추적하고, 다양한 접근 방식을 비교하며, AI 시스템에서 개선이 필요한 영역을 식별할 수 있습니다. 채점기는 자신만의 프롬프트와 점수 매기기 기능으로 사용자 지정할 수 있습니다.

Elasticsearch

데모 프로젝트를 실행하려면 Elasticsearch 인스턴스가 실행 중이어야 합니다. Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

이렇게 하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Mastra 통합 구성에 사용할 API 키가 생성됩니다.

API 키는 이전 명령어의 출력 결과로 표시되며, elastic-start-local 폴더 안에 있는 .env 파일에 저장됩니다.

데모 설치 및 구성

데모 프로젝트의 소스 코드가 포함된 elastic/mastra-elasticsearch-example 리포지토리를 생성했습니다. 리포지토리에 기재된 예제는 Elasticsearch에서 문서를 검색하기 위한 RAG 아키텍처를 구현하는 에이전트를 Mastra에서 생성하는 방법을 보여 줍니다.

Elastic은 데모를 위해 SF 영화에 대한 데이터 세트를 제공했습니다. Kaggle의 IMDb 데이터 세트에서 500개의 영화를 추출했습니다.

첫 번째 단계는 다음 명령어를 사용하여 npm으로 프로젝트의 의존성을 설치하는 것입니다.

그런 다음 설정 정보가 담길 .env 파일을 구성해야 합니다. 다음 명령을 사용하여 .env.example 파일에서 구조를 복사하여 이 파일을 생성할 수 있습니다.

이제 누락된 정보를 추가하여 .env 파일을 편집할 수 있습니다.

Elasticsearch 인덱스의 이름은 scifi-movies입니다. 원한다면 env 변수 ELASTICSEARCH_INDEX_NAME을(를) 사용하여 변경할 수 있습니다.

OpenAI를 임베딩 서비스로 사용했으므로 OPENAI_API_KEY env 변수에 OpenAI용 API 키를 제공해야 합니다.

이 예시에서 사용된 임베딩 모델은 openai/text-embedding-3-small이며, 임베딩 차원은 1,536입니다.

최종 답변 생성을 위해 비용을 절감할 수 있는 openai/gpt-5-nano 모델을 사용했습니다.

RAG 아키텍처를 사용하면 답변의 근거를 찾는 무거운 작업을 검색 구성 요소(이 경우 Elasticsearch)가 처리하기 때문에, 상대적으로 성능이 낮고(따라서 저렴한) 최종 LLM 모델을 사용할 수 있습니다.

소형 LLM은 두 가지 주요 작업만 담당합니다.

• 쿼리 재구성/임베딩: 사용자의 자연어 질문을 의미론적 검색이 가능하도록 벡터 임베딩으로 변환합니다.
• 답변 합성: 정확도가 높고 검색된 컨텍스트 덩어리(문서/동영상)를 가져와서 제공된 프롬프트 지침에 따라 일관성 있고 사람이 읽을 수 있는 최종 답변으로 합성합니다.

RAG 프로세스는 답변에 필요한 정확한 사실적 컨텍스트를 제공하므로 최종 LLM은 거대하거나 매우 복잡할 필요가 없으며, 자체 매개변수 내에서 필요한 지식을 모두 보유할 필요도 없습니다.(이는 보통 크고 비싼 모델들이 맡는 잘하는 것입니다.) 본질적으로 모델은 자체가 거대한 지식 기반 역할을 하는 것이 아니라, Elasticsearch가 제공한 정보를 바탕으로 정교하게 요약하고 형식을 지정하는 역할을 수행하는 것입니다. 이렇게 하면 비용 및 지연 최적화에 gpt-5-nano 같은 모델을 사용할 수 있습니다.

.env 파일 설정을 마친 후, 다음 명령어를 사용하여 영화 데이터를 Elasticsearch으로 수집할 수 있습니다.

다음과 같은 출력 내용이 나타나야 합니다.

SF 영화 인덱스의 매핑에는 다음 필드가 포함되어 있습니다.

• 임베딩, 1,536 차원의 dense_vector, 코사인 유사도.
• 설명, 영화에 대한 설명이 포함된 텍스트.
• 감독, 감독의 이름이 포함된 텍스트.
• 제목, 영화의 제목이 포함된 텍스트.

제목과 설명을 사용하여 임베딩을 생성했습니다. 제목과 설명은 별개의 필드이지만, 이 둘을 연결함으로써 생성된 임베딩 벡터가 영화의 고유한 정체성(제목)과 풍부한 서술적 컨텍스트(설명)을 모두 포착할 수 있게 됩니다. 결과적으로 더욱 정확하고 포괄적인 의미론적 검색이 가능해집니다. 이렇게 결합된 입력은 임베딩 모델에 유사도 매칭을 위한 문서 내용의 더 나은 단일 표현을 제공합니다.

데모를 실행하십시오

다음 명령어를 사용하여 데모를 실행할 수 있습니다.

이 명령어를 실행하면 Mastra Studio에 접속할 수 있는 웹 애플리케이션이 localhost:4111에서 시작됩니다(그림 3).

Mastra Studio는 에이전트를 구축하고 테스트할 수 있는 대화형 UI를 제공하며, Mastra 애플리케이션을 로컬 서비스로 활용할 수 있도록 REST API도 함께 지원합니다. 이를 통해 통합에 대한 걱정 없이 즉시 구축을 시작할 수 있습니다.

Elasticsearch Agent를 제공했으며, 이는 Elasticsearch를 사용하여 의미 검색을 실행하는 도구로 Mastra의 createVectorQueryTool을 사용합니다. 이 에이전트는 RAG 접근법을 사용하여 사용자 질문에 답하기 위한 관련 문서(즉, 영화)를 검색합니다.

이 에이전트는 다음 프롬프트를 사용합니다.

Mastra Studio > Agents 메뉴를 클릭하고 Elasticsearch Agent를 선택하면, 채팅 시스템을 통해 에이전트를 테스트할 수 있습니다. 예를 들어, 다음과 같은 질문으로 SF 영화에 관한 정보를 요청할 수 있습니다.

UFO에 관한 영화 또는 TV 시리즈 5편을 찾아 줘.

에이전트가 vectorQueryTool을 실행하는 것을 확인할 수 있습니다. 실행된 도구를 클릭하여 입력과 출력을 확인할 수 있습니다. 실행이 완료되면 LLM은 Elasticsearch의 SF 영화 인덱스에서 제공된 맥락을 바탕으로 질문에 답변을 제공합니다(그림 4).

Mastra는 내부적으로 다음 단계를 실행합니다.

1. 벡터 변환: 사용자의 질문인 UFO에 관한 영화 또는 TV 시리즈 5편을 찾아 줘는 OpenAI의 openai/text-embedding-3-small 모델을 사용하여 벡터 임베딩으로 변환됩니다.
2. 벡터 검색: 이 임베딩은 벡터 검색을 통해 Elasticsearch를 쿼리하는 데 사용됩니다.
3. 결과 검색: Elasticsearch는 쿼리와 관련성이 높은(즉, 사용자의 쿼리 벡터와 가장 가까운 벡터를 가진) 10편의 영화를 반환합니다.
4. 답변 생성: 검색된 영화와 원래 사용자 질문은 LLM, 구체적으로openai/gpt-5-nano에 전송됩니다. LLM은 이 정보를 처리하여 최종 답변을 생성하며, 이때 결과를 5개 보여달라는 사용자의 요청 사항이 정확히 반영되도록 합니다.

The Elasticsearch Agent

여기에서는 Elasticsearch Agent의 소스 코드를 기재했습니다.

vectorQueryTool은 RAG 예시의 검색 부분을 구현하기 위해 호출되는 도구입니다. Elastic 측에서 Mastra에 기여한 ElasticSearchVector 구현을 사용합니다.

에이전트는 VectorQueryTool, 프롬프트, 메모리를 사용하는 에이전트 클래스의 객체입니다. 보시다시피, Elasticsearch를 에이전트에 연결하기 위해 필요한 코드는 매우 간결합니다.

결론

이 글에서는 Mastra 프레임워크와 Elasticsearch를 통합하여 정교한 에이전트형 AI 애플리케이션을 구축하는 과정이 얼마나 단순하고 강력한지 살펴보았습니다. 특히, Elasticsearch에 인덱싱된 SF 영화 데이터 코퍼스에 대해 의미 검색을 수행할 수 있는 RAG 에이전트를 만드는 방법을 자세히 살펴보았습니다.

핵심적인 특징은 Elastic이 Mastra 오픈소스 프로젝트에 직접 기여했다는 점이며, 이를 통해 Elasticsearch를 벡터 저장소로 사용하는 네이티브 지원이 가능해졌습니다. 이러한 통합은 Elasticsearch Agent 소스 코드에서 확인할 수 있듯이 진입 장벽을 크게 낮춥니다. ElasticSearchVector 및 createVectorQueryTool(을)를 사용하면, 최소한의 구성 코드 몇 줄로 Elasticsearch를 에이전트에 연결하기 위한 전체 설정이 완료됩니다.

Elasticsearch는 결과의 정확도를 향상하고자 여러 고급 기능을 제공합니다. 예를 들어, 하이브리드 검색은 어휘 검색과 벡터 검색을 결합하여 정확도를 크게 향상합니다. 또 다른 흥미로운 기능은 하이브리드 검색의 마지막 단계에 적용할 수 있는 최신 Jina 모델을 활용한 순위 재지정입니다. 이러한 기술에 대해 자세히 알아보려면 Elasticsearch Labs의 다음 글을 참조하세요.

• Elasticsearch 하이브리드 검색, 발렌틴 크레타즈(Valentin Crettaz) 저
• Jina 모델, 그 기능 및 Elasticsearch에서의 사용법에 대한 소개, 스콧 마르텐스(Scott Martens) 저

제공된 예시를 살펴보고 Mastra 및 Elasticsearch로 자신만의 데이터 기반 에이전트를 구축해 보시기 바랍니다. Mastra에 대한 더 자세한 정보는 여기에서 공식 문서를 통해 확인하실 수 있습니다.