기업은 고객 지원 티켓, 법률 문서, 뉴스 피드, 연구 논문 등 방대한 양의 문서를 축적하며, 올바른 질문을 던지기 위해서는 먼저 그 문서에 어떤 내용이 담겨 있는지 정확히 파악해야 합니다 레이블이나 학습 데이터가 없는 상태에서 수천 건의 문서를 수동으로 검토하는 것은 현실적으로 불가능합니다. 무엇을 검색해야 할지 모를 때는 기존 검색 방식이 도움이 되지 않습니다.

이 게시물에서는 이러한 탐색 문제를 해결하는 Elasticsearch 기반의 비지도형 문서 클러스터링 및 시간적 스토리 추적 방식을 안내합니다. 이 과정을 마치고 나면, 여러 날에 걸쳐 전개되는 스토리의 흐름을 다음과 같이 추적할 수 있습니다.

다룰 내용:

• 쿼리 없이 주제를 탐색할 때, (검색용 임베딩이 아닌) 클러스터링 임베딩을 사용하는 것이 왜 중요한가요?
• Elasticsearch의 k-최근접 이웃(kNN)과 배치(Batched) msearch을(를) 활용하여, 밀도 조사 중심 분류 방식이 문서를 주제별로 그룹화하는 방법.
• 모델 학습 없이도 주제를 파악할 수 있도록, significant_text이(가) 클러스터에 자동 레이블 지정을 수행하는 방법.
• 시간적 스토리 체인이 일별 클러스터를 연결하여, 주제가 매일 어떻게 진화하는지를 보여 줍니다.

이 파이프라인은 BBC 뉴스 및 The Guardian에서 제공하는 2025년 2월 기사 약 8,500개를 테스트 코퍼스로 사용합니다. 뉴스는 시간적 흐름이 명확하기 때문에 활용하기 편리하지만, 이러한 패턴은 법률 검토, 규정 준수 모니터링, 연구 종합, 고객 지원 분류 등 문서 탐색이 중요한 모든 곳에 적용될 수 있습니다.

스택:

• Jina v5 클러스터링 임베딩: 주제 그룹화를 위한 작업별 LoRA(Low-Rank Adaptation) 어댑터. Jina가 Elastic과 함께하게 되었습니다. Elastic Inference Service(EIS)에서 Jina 모델을 네이티브로 사용할 수 있습니다.
• Elasticsearch: 확장 가능한 kNN, significant_text 레이블 지정, 및 벡터 스토리지.
• DiskBBQ: 근사 최근접 이웃(ANN) 검색 가속화를 위해 더 나은 이진 양자화(BBQ)와 계층적 K-평균 분할을 결합한 디스크 기반 벡터 인덱스 포맷입니다. 이 인덱스 분할은 벡터 검색 내부에서 이루어지며, 이 게시물에서 사용된 밀도 조사 클러스터링 알고리즘과는 별개입니다. bbq_disk은(는) 양자화된 벡터를 디스크에 저장하고 힙(Heap)에는 분할 메타데이터만 유지합니다. 덕분에 bbq_hnsw과(와) 비교했을 때 높은 재현율을 유지하면서도 리소스 요구 사양을 획기적으로 낮출 수 있습니다.
• 전역 클러스터링 + 일별 시간적 연결: 탐색 및 스토리 진화.

준비 사항:

• Elasticsearch 배포(Elastic Cloud, Elasticsearch Serverless 또는 Elastic Self-Managed 8.18+/9.0+) bbq_disk 을(를) 사용하려면 8.18 이상이 필요합니다. 선택 사항인 다양성 기반 검색기 섹션은 9.3 이상 또는 서버리스가 필요합니다.
• Jina API 키Jina API 키: 무료 티어에는 1,000만 토큰이 포함되어 있으며, 이는 핵심 클러스터링 파이프라인(약 425만 토큰)을 감당할 수 있습니다. 선택 사항인 검색과 클러스터링 비교에는 두 번째 임베딩 패스를 사용합니다.
• Guardian API 키 (무료).

설정

필요한 패키지 설치:

pip install elasticsearch pandas numpy plotly umap-learn python-dotenv pydantic-settings datasets requests

선택 사항(이 리포지토리에서 스크래핑 도우미를 실행하는 경우에만):

pip install beautifulsoup4

그런 다음 프로젝트 루트에 있는 .env 파일에 API 키를 구성하세요.

ELASTIC_CLOUD_ID=your-cloud-id        # or ELASTIC_HOST=https://...
ELASTIC_API_KEY=your-api-key
JINA_API_KEY=your-jina-key
GUARDIAN_API_KEY=your-guardian-key

이 노트북은 load_dotenv(override=True)을(를) 호출하므로, 로컬 .env 값이 우선적으로 적용됩니다.

Connected to Elasticsearch

1부: 탐색 클러스터링 - 왜 임베딩을 클러스터링해야 할까요?

대부분의 벡터 검색은 쿼리와 관련 문서 간의 일치 여부를 판단하도록 학습된 검색용 임베딩을 사용합니다. 검색에는 완벽하지만, 탐색에는 적합하지 않습니다. 쿼리 없이도 코퍼스에 어떤 주제가 존재하는지 찾으려면 유사한 문서를 함께 그룹화하는 임베딩이 필요합니다.

Jina v5는 작업별 LoRA(Low-Rank Adaptation) 어댑터를 통해 이 문제를 해결합니다. LoRA는 모델의 기본 가중치 대부분을 고정한 채, 대상 내부 레이어에 소규모의 저순위 업데이트를 추가합니다. 이를 통해 모델 전체를 재학습시키지 않고도 특정 작업에 맞춰 모델의 동작을 변화시킬 수 있습니다. 동일한 기본 모델이라도 task 매개변수 설정에 따라 서로 다른 임베딩을 생성합니다.

클러스터링 어댑터는 동일한 주제의 문서들은 임베딩 공간에서 더 가깝게, 서로 다른 주제의 문서들은 더 멀리 배치되도록 학습되었습니다. 아래의 시각적 비교 자료를 통해 그 차이를 명확히 확인할 수 있습니다.

검색과 클러스터링: 시각적 비교

그 차이를 확인하기 위해, 두 가지 작업 유형을 각각 모두 적용하여 문서 샘플을 임베딩했습니다. 클러스터링은 원본 데이터인 1024차원의 임베딩 공간에서 수행됩니다. UMAP(Uniform Manifold Approximation and Projection)은 시각화를 위해 이러한 임베딩을 2차원으로 투영하는 용도로만 사용됩니다. UMAP은 데이터의 지역적 이웃 구조를 보존하므로, 클러스터 간의 분리를 비교하는 데 유용합니다.

아래는 동일한 480개의 문서 샘플에 두 가지 작업 유형을 각각 모두 적용하여 임베딩한 후, UMAP을 통해 2차원으로 투영한 결과입니다. 클러스터링 패널에서 더 긴밀하고, 더 명확히 분리된 색상 그룹을 찾습니다.

    Full dataset: 8,495 articles
    Sources: guardian: 5749, bbc: 2746
    Date range: 2025-02-01 to 2025-02-28


    Sample: 480 docs across 8 sections
    section
    Film              60
    World news        60
    Australia news    60
    Opinion           60
    Football          60
    US news           60
    Sport             60
    Business          60


    Clustering embeddings: 480
    Retrieval embeddings:  480


    UMAP projection complete

검색용 임베딩(왼쪽)은 주제를 넓게 퍼뜨리는 반면, 클러스터링용 임베딩(오른쪽)은 동일한 문서에서도 더 긴밀하고 명확하게 구분된 그룹을 형성합니다.

클러스터링 임베딩은 더 긴밀하고 시각적으로도 훨씬 뚜렷하게 구별되는 그룹을 생성합니다. 검색 임베딩은 주제를 더 고르게 분산시켜 검색(세밀한 유사도)에 이상적이지만, 탐색의 경우 긴밀한 주제별 클러스터가 중요합니다.

이것이 바로 본 단계별 안내 나머지 과정에서 task="clustering"을(를) 사용하는 이유입니다.

데이터셋 로딩

코퍼스는 2025년 2월의 두 뉴스 소스를 결합합니다.

• BBC 뉴스: RealTimeData/bbc_news_alltime HuggingFace 데이터셋 활용.
• The Guardian: Guardian Open Platform API활용.

여러 소스의 데이터를 사용하면, 클러스터링이 소스만의 특정 스타일이 아닌 주제를 제대로 찾아내는지 검증하는 데 도움이 됩니다.

    Total articles:  8,495
    
    Source breakdown:
    source
    guardian    5749
    bbc         2746
    
    Date range: 2025-02-01 → 2025-02-28
    Days covered: 28
    
    Sample article:
      Source:  guardian
      Title:   Carbon monoxide poisoning ruled out in death of Gene Hackman and wife, police sa
      Section: Film
      Text:    Authorities have ruled out that Gene Hackman and his wife, Betsy Arakawa, died from carbon monoxide poisoning earlier this week in their home in Santa Fe, New Mexico. The Santa Fe county sheriff, Adan...

클러스터링 작업을 통한 임베딩

모든 문서에 대해 Jina v5 API는 task="clustering" (으)로 호출됩니다. 임베딩은 디스크에 캐시되므로 이후 실행에서는 API를 완전히 건너뜁니다.

API 호출은 간단합니다. task 매개변수는 일반적인 임베딩 사용 방식과 구분되는 가장 핵심적인 차이점입니다.

payload = {
    "model": "jina-embeddings-v5-text-small",
    "input": texts,
    "task": "clustering",  # ← This selects the clustering LoRA adapter
}

아래 실행 시간은 캐시 적중이 적용되었습니다. API를 처음 실행할 때 걸리는 시간은 코퍼스 크기에 따라 달라집니다.

    Embeddings ready: 8,495 vectors of dimension 1024
    Time: 0.6s

단일 Elasticsearch 인덱스로 색인

탐색 클러스터링을 위해, 한 달 전체 데이터를 하나의 인덱스(docs-clustering-all)에 저장합니다. 일일 분할은 시간적 스토리 연결을 위해 나중에 이루어집니다.

인덱스 매핑 시 벡터 필드에 bbq_disk (을)를 사용합니다.

{
  "embedding": {
    "type": "dense_vector",
    "dims": 1024,
    "index": true,
    "similarity": "cosine",
    "index_options": {
      "type": "bbq_disk"        // hierarchical k-means partitioning for ANN index lookup; separate from this post's clustering algorithm
    }
  }
}

1024차원의 float32 벡터는 용량이 4KB입니다. bbq_disk(은)는 계층적 K-평균을 사용하여 벡터를 작은 클러스터로 나누고, 이를 이진 양자화하여 저장한 뒤, 재계산을 위해 전체 정밀도 벡터를 디스크에 보관합니다. 오직 분할 메타데이터만 힙에 상주하므로, 방대한 코퍼스를 처리할 때도 메모리 사용량을 낮게 유지할 수 있습니다. 더 많은 힙을 감당할 수 있는 워크로드의 경우, bbq_hnsw(은)는 리소스 비용이 더 높지만 더 빠른 검색이 가능한 계층적으로 탐색 가능 작은 세계(HNSW) 그래프를 생성합니다.

dense_vector 필드 타입은 다양한 양자화 전략을 지원합니다. 여기서 사용된 1024차원 벡터와 같은 고차원 임베딩에는 bbq_disk 및 bbq_hnsw 방식이 가장 적합합니다.

    Indexed 8,495 documents into docs-clustering-all
    Time: 57.5s

클러스터링: 밀도 조사 중심 분류

HDBSCAN과 같은 전통적인 클러스터링 알고리즘은 N×d 크기의 전체 벡터 행렬을 메모리에 올려 둘 수 있고, 전체 데이터를 반복적으로 훑으며 업데이트를 수행할 수 있다는 가정하에 작동합니다. 1,024차원의 문서 8,495개라면 충분히 감당할 수 있는 크기(35MB 수준)입니다. 하지만 추가적인 인프라 없이는 수백만 건의 문서로 확장하기 어려운 접근 방식입니다.

이 알고리즘은 개념적으로 Voronoi 할당과 노이즈 플로어를 사용하는 KMeans++ 초기화 방식과 유사하지만, Elasticsearch kNN 검색을 연산 프리미티브로 사용하여 거의 모든 작업을 서버 측에서 처리합니다.

1. 전체 문서의 5%를 밀도 조사용으로 샘플링합니다(무작위 샘플, 최소 50개).
2. 배치 처리된msearch kNN을 통해 밀도를 조사합니다. 각 조사 지점에서 kNN 쿼리를 실행해 주변의 평균 유사도를 기록합니다. 높은 평균 유사도는 임베딩 공간의 밀집 영역을 의미합니다. msearch(은)는 단일 HTTP 호출로 여러 검색 요청을 보낼 수 있는데, 이 기능이 여기서 매우 중요합니다. 밀도 조사 과정에서 수백 개의 kNN 쿼리가 생성되는데, 이를 배치로 처리함으로써 요청당 발생하는 오버헤드를 방지할 수 있기 때문입니다.
3. 다양성을 갖춘 고밀도 시드 선택: 밀도 중앙값 이상의 후보들을 밀도 내림차순으로 정렬한 뒤, 모든 기존 시드와의 코사인 유사도가 분리 임계값보다 낮은 경우에만 탐욕적으로 채택합니다. 이것이 유일한 클라이언트 측 연산입니다.(문서 8,000개 기준 약 0.01초 소요)
4. msearch  kNN을 통해 모든 문서를 중심 기준으로 분류: 각 시드가 중심 역할을 수행하며, kNN 검색을 통해 유사도 임계값 이상의 인접 문서를 찾아냅니다. 각 문서는 가장 높은 점수를 반환한 중심에 할당됩니다. 규모가 작은 클러스터들은 해체되어 노이즈로 처리됩니다.

고난도 작업은 Elasticsearch가 처리합니다. 즉, msearch(은)는 밀도 조사에, msearch(은)는 분류에, 그리고 significant_text(은)는 레이블 지정에 활용됩니다. 이 코퍼스(총 8,495개 문서)의 경우, 5%의 밀도 조사용 샘플을 통해 425개의 kNN 조사 쿼리가 실행됩니다. msearch(은)는 이를 9개의 HTTP 호출(배치 크기 50)로 배치 처리함으로써, 개별 조사마다 발생할 수 있는 요청 오버헤드를 방지합니다. 여기에 bbq_disk의 ANN 조회가 결합되어, 클러스터링 단계를 빠르고 확장 가능하게 유지해 줍니다. 클러스터링 단계에서는 속도를 위해 num_candidates 값을 최소화하여 kNN 쿼리를 실행합니다. 반면, 프로덕션 검색 쿼리에서는 지연 시간이 늘어나더라도 재현율을 높이기 위해 더 큰 num_candidates 값을 사용해야 합니다.

클러스터의 크기는 엄격한 k 제한이 아니라, 각 중심 주변의 임베딩 공간 밀도에 따라 자연스럽게 결정됩니다. 밀집된 주제 영역은 더 큰 클러스터를 형성하며, 지엽적인 주제 영역은 더 작은 클러스터를 형성합니다.

KMeans나 HDBSCAN을 사용하지 않는 이유는 무엇일까요?

KMeans는 구형 클러스터를 가정하며 전체 N×d 행렬을 메모리에 저장해야 합니다. 반면, 메모리에 수용 가능한 크기의 코퍼스라면 HDBSCAN이 강력한 대안이 됩니다. 이는 클러스터의 모양에 구애받지 않으며, 밀도 시맨틱이 잘 정립되어 있습니다.

밀도 조사 중심 접근 방식은 다른 지엽적인 영역을 공략합니다. 바로 저장 공간, 검색, 클러스터링을 하나의 시스템 내에서 통합 처리하려 하거나, 데이터 규모 때문에 클라이언트 측에서의 행렬 연산이 실용적이지 못한 경우입니다. Elasticsearch kNN을 컴퓨팅 기본 요소로 사용하고, 임의의 클러스터 크기를 처리하며, 거의 모든 계산을 서버 측에서 수행합니다.

    Clustered global index in 31.6s
      Total clusters: 82
      Total noise:    2420 (28.5%)
      Density probes: 425 kNN queries via 9 _msearch HTTP calls

노이즈 비율에 대한 이해

약 28%의 노이즈 발생률은 의도적으로 설계된 것이며, 오류 모드가 아닙니다. 구성된 similarity_threshold 기준에 따라 어떤 밀집 클러스터에도 적합하지 않은 문서는, 어설픈 매칭을 강행하는 대신 미할당 상태로 남겨 둡니다. 이는 일종의 품질 검사기 역할을 합니다. 사설 칼럼, 단신, 혹은 일회성 기사들은 응집력 있는 그룹을 형성할 만큼의 주제적 밀도가 낮기 때문에 자연스럽게 클러스터링을 거부하게 됩니다.

이 임계값은 조정이 가능합니다. similarity_threshold(을)를 낮추면 더 공격적인 클러스터링이 이루어지며 (더 많은 문서가 할당되지만 군집의 결속력은 느슨해짐) 반대로 높이면 클러스터가 더 긴밀해지는 대신 노이즈 비율이 증가합니다. 다양한 뉴스 콘텐츠가 섞인 이번 코퍼스의 경우, 약 30%의 노이즈 비율은 운용상 적절한 수치입니다. 실제 배포 환경에서는 도메인별 품질 기준에 맞춰 임계값을 조정해야 합니다.

significant_text를 활용한 자동 레이블

이제 각 클러스터에 사람이 읽을 수 있는 레이블을 지정해야 합니다. Elasticsearch의 significant_text 집계는 백그라운드 세트(전체 코퍼스)와 비교했을 때, 포그라운드 세트(클러스터) 내에서 유독 자주 등장하는 용어들을 찾아냅니다.

내부적으로는 머신 러닝이나 거대 언어 모델(LLM) 호출 없이, 절대 빈도와 상대 빈도의 변화를 균형 있게 고려하는 통계적 휴리스틱(기본값으로 JLH 점수 사용)을 활용합니다 영국 정치에 관한 클러스터라면 starmer, labour, downing 같은 용어들이 등장할 것입니다. 이 용어들이 전체 뉴스 코퍼스에 비해 해당 클러스터 내에서 압도적으로 높은 비중을 차지하기 때문입니다.

이번 전체 프로세스에서 레이블은 docs-clustering-all을(를) 기준으로 직접 계산됩니다. 따라서 포그라운드와 백그라운드 모두 한 달 전체 분량에서 추출됩니다. 2부의 레이블링 작업에는 일별 인덱스 패턴(docs-clustering-*)이 사용됩니다. 이 와일드카드 패턴은 쿼리가 모든 일치 인덱스를 동시에 쿼리할 수 있게 하여, significant_text이(가) 더 넓은 백그라운드 바탕으로 더 명확한 대비 효과를 얻을 수 있도록 합니다.

최소한의 쿼리 형태는 다음과 같습니다.

{
  "size": 0,
  "query": { "term": { "cluster_id": "72" } },
  "aggs": {
    "label_terms": {
      "significant_text": {
        "field": "text",
        "size": 5,
        "filter_duplicate_text": true
      }
    }
  }
}

significant_text 또한 품질 검사기 역할도 합니다. 유미의한 용어를 생성하지 않는 클러스터는 구별되는 어휘가 없습니다. 이는 일관성 없는 그룹으로, 오해의 소지가 있는 레이블을 지정하기보다는 다시 노이즈로 해체되어야 합니다.

가벼운 결정론적 정제 단계를 거쳐 노이즈가 섞인 레이블 용어(숫자 토큰, 일반 단어 등)를 제거하며, 필요한 경우 대표적인 헤드라인을 대신 사용합니다. 이를 통해 레이블의 가독성을 높이면서도 Elasticsearch 레이블을 네이티브로 유지할 수 있습니다.

    Sample cluster labels:
      cluster   3  (200 docs)  arsenal | mikel | villa
      cluster   1  (198 docs)  volodymyr | ukrainian | kyiv
      cluster   0  (196 docs)  hostages | hamas | israeli
      cluster   4  (187 docs)  scrum | rugby | borthwick
      cluster  52  (185 docs)  fossil | renewable | renewables
      cluster  10  (156 docs)  labour | gwynne | mps
      cluster  40  (151 docs)  novel | novels | literary
      cluster  11  (149 docs)  mewis | sarina | wiegman
      cluster  44  (143 docs)  flooding | rainfall | rain
      cluster  13  (131 docs)  doge | musk | elon
      cluster  12  (128 docs)  murder | insp | knockholt
      cluster   5  (124 docs)  putin | backstop | starmer


    Reassigned 35 docs from incoherent clusters to noise
    Total docs: 8,495
    Clustered:  6,040 (71.1%)
    Noise:      2,455 (28.9%)

클러스터 시각화

아래 시각화는 전체 클러스터링 과정에서 발견된 결과물입니다. 클러스터링된 문서와 노이즈 문서의 날짜별 구성 현황, 한 달 전체 데이터의 UMAP 투영도, 그리고 클러스터가이 소스가 아닌 주제를 기준으로 형성되었음을 보여 주는 소스 혼합 차트를 확인할 수 있습니다.

2025년 2월 전체 기간에 걸친 클러스터링된 문서와 노이즈 문서의 일일 분포.

UMAP 상의 각 색상별 섬은 클러스터를 나타냅니다. 이는 오직 임베딩 유사도만을 기반으로 발견된, 동일한 주제에 관한 기사 그룹입니다. 회색으로 표시된 노이즈 지점은 어떤 클러스터에도 명확히 속하지 않는 기사들입니다.(주로 짧은 사설, 또는 단발성 뉴스인 경우가 많음)

소스 분류 차트를 통해 각 클러스터에 BBC News와 The Guardian의 기사가 모두 포함되어 있음을 확인할 수 있습니다. 이 클러스터링 시스템은 소스가 아닌 주제를 찾아내고 있으며, 이는 비지도형 탐색이 생성해야 하는 가장 이상적인 결과입니다.

다양성 기반 검색기(diversify retriever)를 사용하여 클러스터 범위를 탐색

일반 kNN은 클러스터의 중심(밀집된 핵심)과 가장 유사한 문서를 반환합니다. 그러나 실제 클러스터는 하위 주제를 다룹니다. 다양성 기반 검색기는 최대 한계 관련성(MMR)을 사용하여, 클러스터 중심과 관련성이 높으면서도 서로 다른 문서들을 찾아냅니다.

핵심 매개변수는 λ(람다)입니다.

• λ = 1.0 → 순수한 관련성(일반 kNN과 동일)입니다.
• λ = 0.0 → 순수한 다양성 (최대한 분산된 결과).
• λ=0.5 → 균형: 주제와 관련이 있지만 다른 관점을 다룹니다.

최소한의 검색기 요청 형태는 다음과 같습니다.

{
  "size": 8,
  "retriever": {
    "diversify": {
      "type": "mmr",
      "field": "embedding",
      "lambda": 0.5,
      "query_vector": "",
      "retriever": {
        "knn": {
          "field": "embedding",
          "query_vector": "",
          "k": 50,
          "num_candidates": 100
        }
      }
    }
  }
}

다양성 수준에서 type, field, query_vector 매개변수는 필수입니다. field(은)는 결과 간 유사도를 측정할 때 어떤 dense_vector 필드를 사용할지 MMR에 지시하며, query_vector(은)는 정확도 점수 산정의 기준점을 제공합니다.

이를 통해 단순히 '이 클러스터의 중심 내용이 무엇인가?'를 파악하는 수준을 넘어, '이 클러스터가 실제로 무엇을 다루고 있는가?' 라는 질문에 답할 수 있습니다.

    Exploring cluster 52 (185 docs)
    Label: fossil | renewable | renewables
    Centroid computed (dim=1024)


    ========================================================================
    Plain kNN (closest to centroid)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9710] Thirteen more oil and gas licences could be cancelled as ministers decide new guidance for fossil fuel extraction after a landmark court...
      3. [0.9699] Experts have accused the fossil fuel industry of seeking special treatment after lobbyists argued greenhouse gas emissions from oilfields...
      4. [0.9681] Burning wood is a terrible way of producing electricity . Chopping down trees destroys habitats for wildlife, and growing new trees cannot...
      5. [0.9649] Keir Starmer will do huge damage to the global fight against climate change if he gives in to political pressure and allows the development...
      6. [0.9641] Labour will next week be confronted with stark policy choices that threaten to expose the fault lines between the Treasury and the...
      7. [0.9638] The Drax power station near Selby in north Yorkshire burns imported wood pellets  The government has agreed a new funding arrangement with...
      8. [0.9581] If you care about the world we are handing on to future generations, the news on Thursday morning was dramatic. This January was the...
    
    ========================================================================
    Diversify retriever (MMR, lambda=0.5)
    ========================================================================
      1. [0.9738] Green campaigners fear ministers are poised to award billions of pounds in fresh subsidies to Drax power station, despite strong concerns...
      2. [0.9434] Oil and gas interests have waged a coordinated campaign to kill pro-electrification policies that ban gas connections in new buildings ,...
      3. [0.9303] It was interesting to read that new licences for oil and gas production in the North Sea are being delayed by legal action ( Thirteen more...
      4. [0.9139] The US energy secretary, Chris Wright, has said he “would love to see Australia get in the game of supplying uranium and maybe going down...
      5. [0.9077] Rachel Reeves was facing criticism on Saturday night as it was confirmed that a report she cited as evidence that a third ­runway at...
      6. [0.8996] When Margaret Thatcher opened the Hadley Centre for Climate Change in 1990 journalists suggested she was attempting to appear to be doing...
      7. [0.8993] The vast majority of governments are likely to miss a looming deadline to file vital plans that will determine whether or not the world has...
      8. [0.8987] European imports of seaborne gas shipments fell by a fifth last year to their lowest level since the pandemic, according to a new report,...
    
    Overlap: 1/8 documents appear in both result sets
    
    Avg pairwise similarity (lower = more diverse):
      Plain kNN:          0.9057
      Diversify retriever: 0.6965

일반 kNN 결과는 주제의 한 가지 관점에 대해서만 클러스터를 이룹니다. 즉, 중심 및 서로 간의 유사도가 가장 높은 문서들만 한데 모이게 됩니다. 다양성 기반 검색기는 동일한 클러스터의 서로 다른 패싯, 즉 하위 주제, 서로 다른 소스, 다양한 관점을 보여 줍니다.

다양성 지표가 이를 수치적으로 증명합니다. 다양성 기반 검색기 결과의 평균 쌍별 유사성이 더 낮게 나타나는데, 이는 검색된 문서가 더 넓은 범위를 다룬다는 것을 의미합니다.

이는 다음과 같은 경우에 유용합니다.

• 클러스터가 실제로 포괄하는 범위가 어디까지인지 이해하려면, 단순히 중심부뿐만 아니라 그 외곽 경계까지 살펴봐야 합니다.
• 요약 생성. 다양한 대표 문서가 LLM에 더 나은 자료를 제공합니다.
• 사람이 직접 검토하거나 후속 레이블 지정에 사용할 대표 사례들을 찾아냅니다.
• 품질 검사. 다양한 결과가 일관성이 없어 보이면 클러스터를 분할해야 할 수도 있습니다.

2부: 시간적 스토리 체인

일자별 스토리 추적

1부에서는 주제 탐색을 위해 한달 전체를 전역으로 클러스터링했습니다. 시간적 흐름을 파악하기 위해, 동일한 밀도 조사 중심 분류를 일별 인덱스에 대해 매일 독립적으로 실행하면, 인접한 날짜 간에 클러스터가 서로 연결됩니다. 참고로 일별 클러스터는 1부의 전역 클러스터와는 별개입니다. 각 날짜마다 그날의 콘텐츠에 맞게 조정된 자체 클러스터 할당과 레이블이 생성됩니다.

연결 방식: 샘플링 후 쿼리

A일의 각 클러스터에 대하여:

1. 몇 개의 대표 문서들을 샘플링합니다.
2. B일의 인덱스를 대상으로 kNN 검색을 실행합니다.
3. B일의 각 클러스터에 검색 결과가 몇 건이나 도달하는지 계산합니다.
4. 검색 결과의 비율이 임계값(kNN fraction ≥ 0.4)을 초과하면, 두 클러스터 사이의 링크를 기록합니다.

이 과정은 빠르며(전체 문서가 아닌 클러스터당 몇 개의 문서만 쿼리하기 때문) Elasticsearch의 네이티브 kNN을 사용하므로 외부 도구가 필요하지 않습니다.

Preparing daily indices for temporal linkage...


Indexed 8,495 docs into 28 daily indices


Temporal links found: 808 in 145.4s

Strongest links:
  2025.02.01 'league | arsenal | premier' -> 2025.02.02 'league | season | striker'  (100%)
  2025.02.03 'league | striker | loan' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.03 'score | operator | gedling' -> 2025.02.04 'league | striker | season'  (100%)
  2025.02.12 'playoff | leg | bayern' -> 2025.02.13 'league | players | injury'  (100%)
  2025.02.14 'league | injury | football' -> 2025.02.15 'league | premier | football'  (100%)
  2025.02.18 'russia | ukraine | talks' -> 2025.02.19 'saudi | russia | arabia'  (100%)
  2025.02.18 'football | league | bayern' -> 2025.02.19 'league | manchester | players'  (100%)
  2025.02.21 'league | premier | manchester' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.21 'rugby | calcutta | brilliant' -> 2025.02.22 'game | players | defeat'  (100%)
  2025.02.26 'metals | kyiv | ukrainian' -> 2025.02.27 'ukraine | russia | talks'  (100%)

kNN 비율이 100%라는 것은 소스 클러스터에서 샘플링된 모든 문서가 동일한 타겟 클러스터에 도달했음을 의미하며, 이는 일자 간에 형성될 수 있는 가장 강력한 링크입니다. 위에서 확인된 대부분의 링크는 축구 관련 내용입니다. 이는 타당한 결과인데, 프리미어 리그 보도는 매일 발생하며 주제의 일관성 또한 매우 높기 때문입니다.

score | operator | gedling → league | striker | season(으)로 이어지는 링크는 지엽적인 로컬 축구 클러스터(Gedling은 비리그 구단임)가 다음 날 더 광범위한 프리미어 리그 클러스터로 흡수되는 과정을 보여 주는 사례입니다. 이는 매일 다른 세부 단위로 다시 클러스터링이 이루어질 때 나타나는 자연스러운 현상입니다.

스토리 체인 구축

스토리 체인은 연속된 날짜에 걸쳐 서로 연결된 클러스터들의 시퀀스입니다.

각각의 쌍별 링크를 통해 월요일의 '영국 정치' 클러스터가 화요일의 클러스터와 연결된다는 사실을 알 수 있습니다. 월요일에 시작된 이야기가 한 주 동안 어떻게 전개되고, 금요일에 이르러 어떻게 잦아드는지, 체인을 통해 스토리의 전체 흐름을 파악할 수 있습니다.

체인은 kNN 비율 0.4 이상의 링크를 바탕으로 탐욕적 방식으로 구축됩니다. 이는 소스 클러스터에서 샘플링된 문서 중 최소 40%가 단일 타겟 클러스터에 매칭되었음을 의미합니다. 가장 이른 시점의 클러스터부터 시작하여, 알고리즘은 항상 가장 강력한 출력 링크를 따라갑니다.

    Strong links (kNN fraction >= 0.4): 244
    Story chains spanning 3+ days: 18
      Chain 1: 'ukrainian | kyiv | eastern' (19 days: Feb 3 → Feb 21)
      Chain 2: 'playing | opposition' (19 days: Feb 10 → Feb 28)
      Chain 3: 'tadhg | maro | cadan' (10 days: Feb 1 → Feb 10)
      Chain 4: 'invade | china | putin' (8 days: Feb 21 → Feb 28)
      Chain 5: 'elected | labour | leader' (7 days: Feb 12 → Feb 18)
      Chain 6: 'film | swift | awards' (6 days: Feb 2 → Feb 7)
      Chain 7: 'amendment | termination | reporting' (6 days: Feb 12 → Feb 17)
      Chain 8: 'officers | scene | police' (5 days: Feb 1 → Feb 5)

가장 긴 스토리 체인은 우크라이나-러시아 관련 보도를 19일 연속으로 추적했는데, 2025년 2월의 지속적인 지정학적 긴장 수위를 고려하면 당연한 결과라 할 수 있습니다. 두 번째로 긴 체인은 한 달 중 19일 동안 이어지는 프리미어 리그 축구 소식을 추적합니다. 더 짧은 체인으로는 시상식 시즌(영화/시상식, 6일), 식스 네이션스 럭비(10일), 그리고 영국 정치 리더십 관련 보도(7일) 등이 포착되었습니다. 각 체인은 알고리즘이 일자별 인덱스 간의 임베딩 유사도만을 바탕으로 순수하게 찾아낸 스토리의 흐름을 나타냅니다.

Sankey: 스토리 흐름 시각화

Sankey 다이어그램은 링크의 폭으로 연결 강도를 표현하는 흐름 시각화 도구입니다. 여기에서 각 수직 밴드는 하루를, 각 노드는 일별 클러스터(문서 수에 따른 크기)를 나타내며, 각각의 색상 경로는 시간을 따라 이어지는 하나의 스토리 체인을 추적합니다. 링크의 폭은 kNN 중첩 강도를 나타냅니다. 링크가 굵을수록 샘플링된 더 많은 문서가 타겟 클러스터에 도달했음을 의미합니다. 체인마다 색상이 일치하므로, 왼쪽에서 오른쪽으로 이어지는 하나의 색상 경로는 하나의 이야기 진행을 나타냅니다.

예를 들어, (가장 긴 경로 중 하나로 시각화된) 우크라이나-러시아 체인은 2월 초부터 셋째 주까지 계속해서 이어지며, 링크의 폭이 지속적으로 굵게 유지되는 것은 일자별로 강력한 주제적 연속성이 있었음을 보여 줍니다.

2025년 2월 한 달간 전개되는 시간적 스토리 체인. 각 색상별 경로는 며칠 동안 지속되는 스토리를 나타내며, 링크 폭은 k-NN 중첩 강도를 보여 줍니다.

이 접근 방식이 제공하는 이점

이 단계별 안내에서는 Elasticsearch를 활용하여 비지도형 문서 클러스터링 파이프라인의 전 과정을 살펴보았습니다.

1. 임베딩 클러스터링: Jina v5의 작업별 어댑터는 단순한 쿼리-문서 매칭을 넘어, 주제별 그룹화에 최적화된 임베딩을 생성합니다.
2. 전역 탐색 클러스터링: 한 달 전체를 하나의 인덱스에 클러스터링하면 일별 주제 탐색을 극대화할 수 있습니다.
3. 밀도 조사 중심 분류: 5%를 샘플링하고, msearch kNN을 통해 밀도를 조사하며, 밀도가 높은 다양한 시드를 선택하고, 모든 문서를 이 중심에 맞춰 분류합니다. 연산량이 많아 무거운 작업은 Elasticsearch가 처리하며, 시드 선택 과정만 클라이언트 측에서 실행됩니다.(약 0.01초 소요)
4. significant_text 레이블 지정: 유의성 검정을 통해 ML 모델이나 수동 주석 없이도 의미 있는 클러스터 레이블을 생성합니다. 유의미한 용어를 생성하지 않는 클러스터는 일관성이 없으며 노이즈로 강등됩니다. 이는 시스템에 내장된 품질 검사기입니다.
5. 시간적 스토리 연결: 일일 인덱스와 샘플 및 쿼리 교차 인덱스 kNN은 시간이 지남에 따라 스토리가 어떻게 진화하는지 추적합니다.

핵심 사항:

• 임베딩 작업 유형 설정이 핵심입니다. 클러스터링 임베딩을 사용하면 주제별 그룹이 훨씬 더 긴밀하게 형성됩니다.
• Elasticsearch는 kNN 검색을 통해 저장 계층 및 클러스터링 엔진 역할을 수행할 수 있습니다.
• 밀도 조사 중심 분류는 거의 모든 연산을 서버 측에서 처리하며, 임베딩 공간의 밀도에 따라 자연스러운 크기의 클러스터를 생성합니다.
• significant_text 빠르고 해석 가능하며 자동 레이블링과 품질 검사 모두에 효과적입니다.

이 방식이 유용한 경우:

• 타임스탬프가 찍힌 텍스트는 있지만, 레이블이 지정된 학습 데이터 없이 주제를 탐색하고 싶을 때 유용합니다.
• 저장 공간, 벡터 검색, 레이블 지정 및 시간적 연결을 하나의 스택으로 해결하고 싶을 때 적합합니다.

탐색할 확장 기능:

• 다중 기간 클러스터링(주간, 월간 단위 집계)
• 클러스터 할당을 점진적으로 수행하여 실시간 데이터 수집이 가능합니다.
• significant_text 용어를 시드로 활용해 LLM이 클러스터 요약문을 생성합니다.
• 규모가 커지면, 샘플링된 KMeans 중심은 밀도 기반 클러스터링을 위한 웜 스타트 시드로 사용될 수 있어, 조사 단계 비용을 줄여 줍니다.

직접 사용해 보기

자신만의 타임스탬프 기반의 문서 코퍼스를 넣어 보세요. 날짜 정보가 포함된 텍스트 모음이라면 무엇이든 이 파이프라인에서 바로 작동합니다. 전체 노트북과 지원 코드는 제공된 리포지토리에서 확인할 수 있습니다.

• 무료 Elastic Cloud 체험판 시작하기: 단 몇 분 만에 bbq_disk 기능이 지원되는 관리형 클러스터를 실행할 수 있습니다.
• Elasticsearch Serverless 사용해 보기: 클러스터 관리가 필요 없으며, 자동으로 확장하고, 이 단계별 안내의 모든 기능을 지원합니다.

어휘 검색(텍스트 매칭), 의미 검색(개념 매칭), 그리고 이 둘을 결합한 하이브리드 검색도 그 자체만으로는 이러한 문제를 해결할 수 없습니다. 어휘 검색은 '오렌지'라는 단어가 포함된 것이라면 무엇이든 반환할 수 있고, 반대로 '오렌지'처럼 고의도 쿼리에 대해 순수 의미 검색을 적용하면 레몬이나 자몽 같은 연관 상품까지 검색 범위가 지나치게 넓어질 수 있습니다. 하이브리드 검색은 어휘 신호와 의미 신호를 혼합하지만, 해당 쿼리를 목적형으로 간주할지, 어떤 제약 조건을 적용할지, 혹은 어떤 비즈니스 정책을 적용할지는 여전히 결정하지 못합니다. 결국 문제는 검색 기술 그 자체에 있는 것이 아닙니다. 이 쿼리가 어떤 성격인지 파악하고, 검색이 시작되기도 전에 어떤 제약 조건을 적용해야 하는지 판단하는 거버넌스 계층이 없다는 것이 핵심 문제입니다.

이 블로그에서는 전자 상거래 검색 거버넌스란 무엇인지, 왜 중요한지, 그리고 제어 계층이 어떻게 예측 가능하고 정확한 검색 결과를 보장하는지 자세히 살펴봅니다.

전자 상거래 검색에서 거버넌스가 의미하는 것

이러한 맥락에서 거버넌스는 사용자의 쿼리와 검색 엔진 사이에 의사 결정 계층을 도입하는 것을 의미합니다. 이 계층은 다음과 같은 기능을 수행합니다.

• 쿼리 의도 분류: 이 검색이 목적형('오렌지')인가요, 아니면 발견형('할아버지를 위한 선물')인가요?
• 비즈니스 제약 조건 적용: 어떤 카테고리 경계, 적격성 규칙, 재고 가용성 제약, 또는 머천다이징 정책을 적용해야 할까요?
• 적절한 전략으로 가는 방법: 어휘 검색, 의미 검색, 하이브리드 중 어떤 것을 사용해야 할까요?

거버넌스 계층은 각 쿼리에 사용할 검색 접근 방식, 적용해야 하는 제약 조건, 검색을 시작하기 전에 적용해야 하는 비즈니스 정책을 결정합니다. 거버넌스와 하이브리드 검색을 혼동하지 않는 것이 중요합니다. 하이브리드 검색은 어휘와 의미 신호를 결합한 하나의 검색 전략일 뿐이지만, 거버넌스는 어휘, 의미, 하이브리드 중 어느 방식을 사용할지 결정하는 상위 의사 결정 계층입니다.

현재 상태: 애플리케이션 계층 "스파게티" 구현

현재 많은 소매 업체에서 이 문제를 해결하기 위해 애플리케이션 계층에 직접 로직을 추가하려고 시도합니다. 이로 인해 종종 하드코딩된 수천 줄의 if-then 문, 정규 표현식 및 복잡한 검색 템플릿으로 뒤엉킨 스파게티 코드라는 결과가 초래됩니다.

이러한 방식은 앞서 살펴본 것처럼 원하는 검색 결과를 제공할 수는 있지만, 운영상 상당한 마찰을 초래한다는 문제가 있습니다.

• 엔지니어링 의존성: 비즈니스 사용자와 머천다이저는 엔지니어링 티켓을 발행하고 대개 몇 주씩 걸리는 긴 배포 주기를 거치지 않고서는 검색 동작을 조금도 수정할 수 없습니다.
• 파편화: 검색 로직이 애플리케이션 코드와 검색 템플릿 사이에 흩어져 있으면 논리적 근거를 설명하거나 감사하기가 어려워지며, 이는 결국 발전 과정에 위험을 초래합니다.

팀에서 라우팅의 필요성을 인식하더라도 '어떤 검색 방법을 선택해야 하는가'라는 잘못된 질문에 초점을 맞추는 경우가 많습니다.

잘못된 논쟁: 어휘 검색, 의미 검색, 그리고 하이브리드 검색 사이의 선택

검색 팀은 흔히 '어휘/BM25 검색이냐, 의미/벡터 검색이냐, 아니면 하이브리드냐'와 같이 어떤 검색 전략을 채택할 것인가를 결정하는 것이 가장 큰 과제라고 생각하곤 합니다. 이러한 관점이 이해되지 않는 것은 아닙니다(검색 방식은 중요합니다). 하지만 이는 실제 배포 환경에서 가장 흔히 발생하는 실패 유형을 간과하고 있습니다. 바로 모든 쿼리에 단일 검색 방식만 사용하다가 결국 최적의 결과를 내지 못하는 상황입니다.

전자 상거래 검색은 근본적으로 서로 다른 의도가 혼합된 것입니다.

• 확정적인 고의도 목적형 검색('오렌지', '우유', '땅콩 없는 초콜릿', '저렴한 올리브 오일').
• 탐색형 검색('산악용 재킷', '로봇 공학을 좋아하는 12세 어린이를 위한 선물').
• 운영상의 제약 조건(재고 가용성, 크기, 가격, 색상).
• 머천다이징 및 캠페인(상위 노출, 하위 노출, 시즌 캠페인).

시스템이 이처럼 다양한 의도를 모두 동일한 검색 전략으로 라우팅하면, 결과는 흔히 계통적인 오류를 범하게 됩니다. 이는 예측 가능한 실패인데, 운영 모델에 거버넌스가 부재하여 발생하기 때문입니다. 팀이 이를 거버넌스의 공백으로 인식하지 못하면, 결국 팀이 가진 유일한 해결 수단인 추가적인 조정으로 대응합니다.

'정확도 조정'이 악순환이 되는 이유

라우팅 계층이 없으면, '정확도 개선' 작업은 흔히 끝이 보이지 않는 무한한 백로그로 변질되곤 합니다.

• 이 쿼리에서 핵심 제품 위에 액세서리가 표시되는 이유는 무엇인가요?
• 왜 갑자기 이 헤드 쿼리에서 관련 항목들이 나타나기 시작했나요?
• 동의어를 추가하고, 분석기를 조정하거나 하이브리드 검색을 활성화했는데, 왜 검색 결과가 변한 걸까요?
• 검색어 하나를 수정하는 데 왜 비즈니스 팀이 엔지니어링 배포까지 기다려야 하나요?

팀은 동의어 추가, 상위 노출, 순위 재지정 실험, 애플리케이션 코드 내 예외 로직 삽입과 같은 더 많은 조정으로 대응합니다. 이 방식이 당분간은 통할지 모르나, 시스템이 여전히 쿼리 유형을 결정하고 검색 전에 올바른 제약 조건을 적용하는 명시적인 결정 계층이 부족하기 때문에 취약한 동작 일으킵니다.

전자 상거래 의도 파헤치기: 헤드와 테일

이 섹션에서는 전자 상거래에서 흔히 나타나는 목적형(Navigational) 및 탐색형(Exploratory) 쿼리 패턴을 실무적으로 구분하기 위해, 이를 각각 ‘헤드(Head)’와 ‘테일(Tail)’이라는 약어로 지칭하겠습니다. 실제 환경에서는 많은 쿼리가 두 가지 측면을 모두 포함하는 경우가 많습니다.

헤드 쿼리(확정적 의도)

이는 사용자가 원하는 바를 정확히 알고 입력하는 직접적이고 목적성 뚜렷한 쿼리입니다.

• 단일 항목 의도 ('오렌지', '우유', '빵').
• 정확한 브랜드 또는 제품군('iPhone 15 Pro' '다이어트 콜라').
• SKU, 모델 번호, 크기('ABC123', 'air max 270').

이런 쿼리들의 경우, 어휘 검색만으로도 토큰 대응(일치하는 단어)을 충분히 처리할 수 있습니다. 하지만 비즈니스는 제약 조건을 준수하고, 예측 가능한 순위를 반환하며, 결과를 직접 제어할 수 있기를 기대합니다. 머천다이저는 쿼리가 정확한 카테고리 범위 내에서 도출되고, 구매 자격을 준수하며, 특정 비즈니스 우선순위가 반영되도록 보장해야 합니다.

의도한 도출 결과를 시행하기 위해서는 거버넌스가 필요합니다. 예를 들어, '오렌지'는 오렌지 주스, 오렌지 마멀레이드, 오렌지 소다가 아니라 반드시 농산물 카테고리로 연결되어야 합니다.

테일 쿼리(탐색형 검색)

이는 쇼핑객이 상품을 탐색할 때 나타나는 설명적이고 의도가 명확한 쿼리입니다.

• ‘단것을 좋아하는 할아버지를 위한 선물’
• '산악용 외투'
• '오래 서 있어도 편한 신발'

이러한 쿼리에서는 어휘 검색이 제 성능을 발휘하지 못하는 경우가 많습니다. 의미 검색은 단어가 정확히 일치하지 않더라도 쿼리의 개념과 상품을 연결할 수 있기 때문에 이러한 경우에 매우 탁월합니다. 그러나 의미 검색만으로도 충분하지 않은 경우도 많습니다. 실제 쿼리에서는 어떤 검색 방식을 사용하든 상관없이, 반드시 준수되어야 하는 제약 조건들이 있기 마련입니다.

제약 조건은 검색 방식과 무관

의미 검색에 제약 조건을 적용하는 것이 하이브리드 검색을 의미하는 것은 아닙니다. 이것들은 서로 무관합니다. Elasticsearch의 필터 및 상위 노출 같은 제약 조건은 어휘, 의미 또는 하이브리드 검색에 모두 적용할 수 있습니다. 관건은 이 쿼리를 어떻게 해석할지, 어떤 제약 조건을 적용할지, 그리고 어떤 검색 전략을 사용할지 결정하는 것입니다.

아래는 검색과 엄격한 제약 조건을 결합한 쿼리의 몇 가지 예시입니다.

• 오렌지: '오렌지'에 대한 어휘 검색과 '과일' 또는 '농산물'과 같은 카테고리 제약 조건을 추가하여 오렌지 마멀레이드, 오렌지 주스, 오렌지 소다를 제외합니다.
• 4달러 미만의 비타민 C 함량이 높은 과일: 영양학적 의도에 기반한 의미 검색을 수행하되, 결과를 과일 카테고리 및 4달러 미만 제품으로 제한하는 제약 조건을 적용합니다.
• 업무용 편안한 신발: 문맥적 의도에 따른 의미 검색을 수행하되, 결과를 신발로 제한하는 제약 조건을 적용합니다.

이러한 쿼리는 단일 방법으로 처리할 수 없습니다.

• 순수 어휘 검색만으로는 충분하지 않은 경우가 많습니다. '비타민 C 함량이 높은'이나 '편안한' 같은 문구들은 깔끔하고 구조화된 속성으로 존재하지 않을 수 있기 때문입니다. 제품 설명, 리뷰 또는 사양을 통해 추론해야 할 수도 있습니다.
• 또한 순수 의미 검색으로도 항상 충분하지 않습니다. 명시적인 제약 조건이 없으면 '비타민 C 함량이 높은 과일'과 같은 쿼리가 의도한 카테고리와 가격 범위를 넘어 비타민 보충제, 과일 맛 음료 또는 비타민 함량이 높은 채소로 확대될 수 있습니다.

거버넌스 계층은 쿼리에 어휘 검색, 의미 이해, 제약 조건 적용 또는 이것들의 조합이 필요한지를 결정합니다. 이 계층이 없으면 전자 상거래 팀은 다음과 같은 상황에 처할 수 있습니다.

• 과도한 제약: 의미 요청에 어휘 검색을 사용(예: '할아버지를 위한 선물')합니다.
• 제약 조건 미달: 고의도 헤드 쿼리(예: '오렌지')에 의미 쿼리를 사용합니다.

거버넌스의 과제는 각 쿼리 유형에 대해 적절한 판단을 내릴 수 있는 시스템을 구축하는 것입니다.

거버넌스가 부재할 경우 발생하는 문제

가장 흔한 실패 유형은 단순합니다. 바로 중간 거버넌스 계층 없이, 사용자 쿼리 그대로를 단일 검색 전략(어휘, 의미 또는 하이브리드)에 직접 전달하는 것입니다.

의도한 결과를 도출하지 못하는 어휘 검색

사용자가 '오렌지'를 검색할 때, 어휘 검색 전략은 해당 토큰이 포함된 모든 상품, 즉 오렌지 주스, 오렌지 마멀레이드, 오렌지 소다 등을 모두 결과로 반환할 수 있습니다. 시스템은 용어를 올바르게 일치시켰지만, 거버넌스 없이는 의도한 쇼핑 맥락(과일)을 도출하지 못할 수 있습니다.

의도한 제약 조건을 넘어 확장하는 의미 검색

사용자가 '오렌지'를 검색할 때, 의미 시스템은 주변 제품 개념 전반에 걸쳐 개념적으로 관련된 항목을 검색할 수 있습니다. 시스템은 더 넓은 영역(과일이나 농산물)을 정확히 이해할 수 있지만, 명시적인 거버넌스 없이는 여전히 사용자가 의도한 제약 조건(특히 오렌지)을 넘어 범위가 지나치게 넓어질 수 있습니다.

문제의 핵심은 결국 거버넌스

필요한 것은 검색이 시작되기 전, 쿼리의 의도를 파악하고 적절한 제약 조건을 강제하는 업스트림 의사 결정 계층입니다. 이렇게 하면 다음과 같은 문제가 해결됩니다.

• 사용자가 실제로 원했던 항목과 유사하거나 관련된 항목이 함께 표시됩니다.
• 모호한 카테고리 경계(예: '음료'와 '농산물'의 혼선).
• 시즌별 상위 노출이나 캠페인 실행 불가.
• 예측할 수 없고 설명할 수 없는 결과.

의도 이해 및 라우팅: 반드시 필요한 제어 평면

거버넌스가 적용된 검색 시스템은 검색 실행 전(Elasticsearch에서 쿼리를 수행하기 전) 단계에 경량화된 제어 평면을 도입합니다. 제어에 대한 자세한 내용은 이번 블로그 시리즈의 3부와 4부에서 다룰 예정입니다. 지금은 이 계층이 어떻게 작동하는지보다는 무엇을 할 수 있는지를 중심으로 살펴보겠습니다.

제어 평면은 의도를 파악하고, 비즈니스 정책을 적용하며, 다음과 같이 적절한 검색 전략을 보장할 수 있습니다.

1. 의도 신호 감지

• 이 쿼리는 목적을 위한 것인가요, 아니면 발견을 위한 것인가요?
• 이미 알고 있는 헤드 쿼리(우유, 빵, 바나나)인가요?
• 이미 알고 있는 제품, 브랜드 또는 카테고리 해석이 있나요?(예: '오렌지'는 농산물로 도출해야 함).
• 쿼리가 SKU와 유사한 패턴인가요?
• 쿼리가 현재 진행 중인 캠페인이나 시즌 정책에 해당하나요?(예: 크리스마스 기간 중 칠면조 관련 검색 결과에 상위 노출)
• 해당 쿼리에 제약 조건(카테고리, 속성, 제외 항목, 가격/크기/색상)이 포함되어 있습니까?

2. 거버넌스 및 비즈니스 정책 적용

• 확정적 제약 조건(카테고리/속성/제외 조건/재고 가용성)을 먼저 적용합니다.
• 활성화된 머천다이징 정책(상위 노출, 하위 노출, 위치 고정, 결과 재정의)을 적용합니다.
• 우선순위 규칙에 따라 충돌을 해결합니다(예: 캠페인 재정의와 글로벌 정책 간의 충돌).

3. 적절한 검색 전략으로 라우팅

• 목적형/고의도 헤드 쿼리를 위한 어휘(빠르고 확정적)입니다.
• 진정한 발견형 쿼리를 위한 의미 검색입니다.
• 명시적인 비즈니스 제약 조건하에, 어휘 및 의미 신호를 결합하여 가치를 더하는 하이브리드 방식입니다.

실제로, 제어 평면의 출력은 단순히 '하이브리드 사용' 또는 '의미 사용'이 아닙니다. 이것이 바로 거버넌스 기반의 검색 계획입니다. 즉, 쇼핑객의 의도를 해석하고, 적용해야 할 제약 조건과 정책을 결정하며, 실행할 검색 전략을 수립합하는 것입니다. 몇 가지 간단한 사례를 통해 이를 구체적으로 살펴보겠습니다.

제어 평면은 각 쿼리에 대해 일관되고 예측 가능하며 확장 가능한 방식으로 적절한 정책과 검색 전략을 선택합니다. 이러한 방식은 의도에 부합하는 제약 조건을 최우선으로 적용하고 라우팅 결정을 명시화함으로써, 프로덕션에서 고도화된 검색 방법의 예측 가능성을 높여 줍니다.

다른 접근 방식과의 관계

일부 팀은 제품 의미를 더 잘 파악하기 위해 개선된 임베딩 모델을 사용하여 의미 검색 품질을 실질적으로 향상할 수 있습니다. 또 어떤 팀은 검색 후 참여도 또는 비즈니스 신호를 기반으로 결과 순서를 최적화하기 위해 LTR(Learning To Rank)과 같은 순위 재지정 방식을 사용하기도 합니다. 두 방식 모두 가치 있으며, 대개 상호 보완적입니다. 더 나은 임베딩은 유사성 매칭을 개선합니다. 순위 재지정은 검색된 후보 사이의 노출 순서를 개선합니다.

거버넌스는 검색의 업스트림에 위치한다는 점에서 다른 계층의 문제를 다룹니다. 제어 평면은 어떤 검색 전략(어휘, 의미, 또는 하이브리드)을 사용할지, 어떤 확정적 제약 조건을 적용할지, 그리고 어떤 쿼리가 여러 비즈니스 정책을 결합할지를 결정합니다.

거버넌스 기반의 제어 평면을 통해 가능한 것

거버넌스 계층이 구축되면 운영 모델이 근본적으로 바뀝니다. 수익에 직결되는 핵심 쿼리의 결과가 예측 가능해집니다. 비즈니스 팀은 엔지니어링팀의 배포 주기를 기다리지 않고도 검색 동작을 업데이트할 수 있습니다. 또한 의미 및 하이브리드와 같은 고급 검색 방법을 전체 시스템의 온/오프 스위치 대신 라우팅 및 가드레일 뒤에서 점진적으로 도입할 수 있습니다.

이 시리즈의 다음 게시물에서는 이러한 운영 모델이 실제로 어떻게 작동하는지, 그리고 왜 이 모델이 그 기반이 되는 검색 기술만큼이나 중요한지를 살펴봅니다.

머천다이저가 수익에 직결되는 핵심 쿼리 문제를 해결하기 위해 Jira 티켓을 생성하고 배포를 기다려야 한다면, 그 병목 지점은 검색 엔진이 아니라 운영 모델에 있는 것입니다. 현대 전자 상거래 검색은 비즈니스 의도를 제어되고 감사 가능한 검색 동작으로 신속하고 안전하게 변환하는 방법이 필요하며, 동시에 고도화된 검색은 실질적인 가치를 더할 수 있는 경우 고급 검색 기능을 활용해야 합니다.

이 시리즈의 다음 내용

이 시리즈에서 살펴본 패턴은 검색의 업스트림에서 작동합니다. 즉, 쿼리 생성이 시작되기도 전에 비즈니스 의도를 최적의 검색 전략으로 변환합니다. 다음 게시물에서는 기술적인 문제에서 운영의 영역으로 관점을 옮겨보겠습니다. 비즈니스 팀이 엔지니어링 배포 없이 검색 동작을 직접 수정할 수 있게 될 때 어떤 변화가 일어나는지, 그리고 거버넌스가 어떻게 그 과정을 안전하게 보장하는지 살펴봅니다.

거버넌스 기반 전자 상거래 검색 실제로 적용해 보기

엔지니어링 병목 현상, 취약한 애플리케이션 계층 로직, 예측할 수 없는 검색 결과는 엔터프라이즈 전자 상거래 서비스 계약을 통해 Elastic 서비스가 해결할 수 있는 문제입니다. 본 시리즈에서 설명하는 거버넌스 기반 제어 평면 아키텍처는 Elastic Services Engineering에서 구축했습니다.

여러분의 팀이 머천다이징 요청을 코드로 옮기는 데 엔지니어링 주기를 허비하고 있거나, 검색 정확성 백로그가 좀처럼 줄어들지 않는다면 Elastic이 도와드릴 수 있습니다. 현재 아키텍처를 평가하고 거버넌스 기반의 기업이 편집 가능한 검색 환경을 구축하는 데 도움을 드릴 수 있습니다. Elastic Services에 문의하세요.

논의에 참여하기

검색 거버넌스, 검색 전략 또는 전자 상거래 검색 아키텍처에 대해 궁금한 점이 있으신가요? Elastic 커뮤니티 대화에 참여하세요.

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

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

Mastra

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

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

src/
├── mastra/
│   ├── agents/
│   │   └── weather-agent.ts
│   ├── tools/
│   │   └── weather-tool.ts
│   ├── workflows/
│   │   └── weather-workflow.ts
│   ├── scorers/
│   │   └── weather-scorer.ts
│   └── index.ts
├── .env.example
├── package.json
└── tsconfig.json

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

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

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

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

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

Elasticsearch

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

curl -fsSL https://elastic.co/start-local | sh

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

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

데모 설치 및 구성

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

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

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

npm install

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

cp .env.example .env

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

OPENAI_API_KEY=
ELASTICSEARCH_URL=
ELASTICSEARCH_API_KEY=
ELASTICSEARCH_INDEX_NAME=scifi-movies

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으로 수집할 수 있습니다.

npx tsx src/utility/store.ts

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

🚀 Starting ingestion of 500 movies from 500_scifi_movies.jsonl...
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 1/500 (0%) | ok:1 | fail:0 | chunks:1 | eta:19m 33s | current:Capricorn One
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 2/500 (0%) | ok:2 | fail:0 | chunks:2 | eta:10m 32s | current:Doghouse
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 3/500 (1%) | ok:3 | fail:0 | chunks:3 | eta:7m 33s | current:Dinocroc
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 4/500 (1%) | ok:4 | fail:0 | chunks:7 | eta:6m 10s | current:Back to the Future           
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 5/500 (1%) | ok:5 | fail:0 | chunks:9 | eta:5m 14s | current:The Projected Man            
Ingesting ░░░░░░░░░░░░░░░░░░░░░░░░ 6/500 (1%) | ok:6 | fail:0 | chunks:11 | eta:4m 41s | current:I, Robot
...
✅ Ingestion complete in 1m 46s. Success: 500, Failed: 0, Chunks: 693.

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

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

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

데모를 실행하십시오

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

npm run dev

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

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

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

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

You are a helpful assistant that answers questions based on the provided context.
Follow these steps for each response:

1. First, carefully analyze the retrieved context chunks and identify key information.
2. Break down your thinking process about how the retrieved information relates to the query.
3. Draw conclusions based only on the evidence in the retrieved context.
4. If the retrieved chunks don't contain enough information, explicitly state what's missing.

Format your response as:
THOUGHT PROCESS:
- Step 1: [Initial analysis of retrieved chunks]
- Step 2: [Reasoning based on chunks]

FINAL ANSWER:
[Your concise answer based on the retrieved context]

Important: When asked to answer a question, please base your answer only on the context provided in the tool. 
If the context doesn't contain enough information to fully answer the question, please state that explicitly and stop it.
Do not add more information than what is present in the retrieved chunks.
Remember: Explain how you're using the retrieved information to reach your conclusions.

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의 소스 코드를 기재했습니다.

import { Agent } from "@mastra/core/agent";
import { ElasticSearchVector } from '@mastra/elasticsearch';
import { createVectorQueryTool } from '@mastra/rag';
import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
import { Memory } from "@mastra/memory";

const es_url = process.env.ELASTICSEARCH_URL;
const es_apikey = process.env.ELASTICSEARCH_API_KEY;
const es_index_name = process.env.ELASTICSEARCH_INDEX_NAME;
const prompt = 'insert here the previous prompt';

const esVector = new ElasticSearchVector({
  id: 'elasticsearch-vector',
  url: es_url,
  auth: {
    apiKey : es_apikey
  }
});

const vectorQueryTool = createVectorQueryTool({
  vectorStore: esVector,
  indexName: es_index_name,
  model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small")
});

export const elasticsearchAgent = new Agent({
  id: "elasticsearch-agent",
  name: "Elasticsearch Agent",
  instructions: prompt,
  model: 'openai/gpt-5-nano',
  tools: { vectorQueryTool },
  memory: new Memory(),
});

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에 대한 더 자세한 정보는 여기에서 공식 문서를 통해 확인하실 수 있습니다.

Elastic Workflows는 Kibana에 내장된 자동화 엔진입니다. 간단한 YAML 설정을 통해 여러 단계로 구성된 프로세스를 정의할 수 있습니다. 각 워크플로우는 일정 또는 이벤트에 따라 트리거될 수 있으며 Elastic Agent Builder의 도구로 활용할 수 있습니다. 또한 각 단계에서 Kibana API 호출, Elasticsearch 쿼리 실행, 데이터 변환 작업을 수행할 수 있습니다.

여기서는 대시보드 조회수를 구체적인 예로 사용하지만 Kibana saved objects API를 통해 노출되는 모든 메트릭에 동일한 패턴을 적용할 수 있습니다.

필수 구성 요소

• 9.3 버전이 실행 중인 Elastic Cloud 또는 자체 관리형 클러스터
• 워크플로우 기능 활성화(고급 설정)

본격적인 구축에 앞서 우리가 활용할 데이터가 어떤 구성을 갖추고 있는지 먼저 이해해 봅시다. Kibana는 대부분의 설정 정보와 메타데이터를 전용 내부 인덱스에 Saved Objects라는 형태로 저장합니다. Kibana가 이러한 방식으로 추적하는 항목 중 하나는 대시보드 조회수입니다. 이때 'Usage Counters'라는 특수한 유형의 Saved Object를 사용하게 됩니다. 다음과 같이 Dev Tools에서 직접 쿼리할 수 있습니다.

GET kbn:/api/saved_objects/_find?type=usage-counter&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"&per_page=10000

응답은 다음과 같습니다.

{
  "page": 1,
  "per_page": 10000,
  "total": 1,
  "saved_objects": [
    {
      "type": "usage-counter",
      "id": "dashboard:346f3c64-ebca-484d-9d57-ec600067d596:viewed:server:20260310",
      "attributes": {
        "domainId": "dashboard",
        "counterName": "346f3c64-ebca-484d-9d57-ec600067d596",
        "counterType": "viewed",
        "source": "server",
        "count": 1
      },
      ...
    }
  ]

counterName 필드는 대시보드의 ID를 나타내며 count는 해당 특정 날짜의 대시보드 누적 조회수입니다. Kibana는 대시보드당 하루에 하나의 카운터 객체를 생성합니다. 객체 ID의 날짜 접미사(예: ...viewed:server:20260310)를 통해 이를 확인할 수 있습니다. 조회수는 사용자가 대시보드를 열 때마다 하루 동안 계속해서 증가합니다.

인덱스에 이러한 일일 문서 모델을 그대로 복제하는 대신 워크플로우 실행당 하나의 문서를 생성해 보겠습니다. 각 문서는 캡처 시점을 기준으로 해당 대시보드의 당일 누적 조회수를 기록합니다.

2단계: 대상 인덱스 생성

대시보드 조회 스냅샷을 저장할 인덱스가 필요합니다. 나중에 집계와 시각화가 가능하도록 명시적 매핑을 사용하여 다음과 같이 인덱스를 생성합니다. Dev Tools에서 다음 명령을 실행하세요.

PUT dashboard-views
{
  "mappings": {
    "properties": {
      "captured_at": {
        "type": "date"
      },
      "dashboard_id": {
        "type": "keyword"
      },
      "dashboard_name": {
        "type": "keyword"
      },
      "view_count": {
        "type": "integer"
      }
    }
  }
}

ID와 이름에 keyword 매핑을 사용하면 집계를 수행할 수 있습니다. view_count에 integer 타입을 사용하는 것은 안전한 기본값입니다. Kibana는 카운터를 매일 초기화하므로 32비트 제한(하루 20억 회 이상의 조회수)에 도달하는 것은 현실적인 우려 사항이 아니기 때문입니다. 이 타입은 여전히 max, avg, min과 같은 수치 연산을 지원합니다.

3단계: 워크플로우 생성

Stack Management > Workflows > New Workflow 메뉴로 이동한 뒤 아래의 워크플로우 YAML 설정 내용을 복사하여 붙여넣으세요.

name: dashboard-views-ingestion
triggers:
  - type: scheduled
    with:
      every: 30m

steps:
  - name: fetch_dashboard_views
    type: kibana.request
    with:
      method: GET
      path: >-
        /api/saved_objects/_find?type=usage-counter&per_page=10000&filter=usage-counter.attributes.domainId:"dashboard"%20and%20usage-counter.attributes.counterType:"viewed"

  - name: index_each_dashboard
    type: foreach
    foreach: "{{ steps.fetch_dashboard_views.output.saved_objects }}"
    steps:
      - name: fetch_dashboard_name
        type: kibana.request
        with:
          method: GET
          path: /api/saved_objects/dashboard/{{ foreach.item.attributes.counterName }}
        on-failure:
          continue: true

      - name: index_doc
        type: elasticsearch.request
        with:
          method: POST
          path: /dashboard-views/_doc
          body:
            dashboard_id: "{{ foreach.item.attributes.counterName }}"
            dashboard_name: "{{ steps.fetch_dashboard_name.output.attributes.title }}"
            view_count: "${{ foreach.item.attributes.count | plus: 0 }}"
            captured_at: "{{ execution.startedAt | date: '%Y-%m-%dT%H:%M:%SZ' }}"

다음 섹션에서는 워크플로를 단계별로 자세히 살펴봅니다.

워크플로우 작동 방식

트리거

워크플로우는 30분 간격의 예약된 트리거에 따라 실행됩니다. 이를 통해 API에 무리를 주지 않으면서도 시계열 데이터를 확보할 수 있습니다.

fetch_dashboard_views

kibana.request를 사용하여 Kibana Saved Objects API를 호출합니다. 별도의 인증 설정은 필요하지 않습니다. 워크플로우 엔진이 실행 컨텍스트에 따라 적절한 헤더를 자동으로 첨부하기 때문입니다.

index_each_dashboard (foreach)

이전 단계에서 반환된 saved_objects 배열을 순회합니다. 각 반복에서 현재 항목은 foreach.item을 통해 접근할 수 있습니다. 루프 내부에서는 각 대시보드에 대해 두 개의 하위 단계를 실행합니다.

1. fetch_dashboard_name:

GET /api/saved_objects/dashboard/{id}를 호출하여 사용자가 읽을 수 있는 대시보드 제목을 확인합니다. on-failure: continue: true설정을 추가합니다. 이를 통해 특정 대시보드가 삭제되었더라도 조회수 카운터가 남아있는 경우 전체 실행이 실패 처리되지 않고 루프가 계속 지속됩니다.

2. index_doc:

POST /dashboard-views/_doc을 사용해 명시적 ID 없이 각 문서를 인덱싱하며 이 과정에서 Elasticsearch가 ID를 자동으로 생성합니다. 이는 실행할 때마다 새로운 문서를 생성합니다. 이전 스냅샷을 덮어쓰지 않고 시간에 따른 조회수 이력을 쌓을 수 있습니다.

주목할 만한 두 가지 사항이 있습니다:

• captured_at 필드는 날짜 필터를 사용하여 타임스탬프를 ISO 8601 형식으로 변환합니다. 이 설정이 없으면 값이 Tue Mar 10 2026 05:03:47 GMT+0000과 같은 JavaScript 날짜 문자열로 출력됩니다. 이 경우 Elasticsearch가 이를 날짜 형식으로 매핑하지 못합니다.
• view_count는 숫자 유형을 유지하기 위해 ${{ }} 구문과 | plus: 0을 사용합니다. 단순히 {{ }}를 사용하면 값이 문자열로 렌더링되어 대시보드에서 수치 연산을 수행할 수 없게 됩니다.

UI를 통해 워크플로의 각 단계를 편리하게 디버깅할 수 있습니다.

4단계: 통계 대시보드 구축

워크플로우가 몇 번 실행되어 데이터가 수집되면 dashboard-views 데이터 뷰를 사용하여 Kibana에서 새 대시보드를 만듭니다.

활용 가능한 패널 예시:

• 조회수별 주요 대시보드: X축에 dashboard_name을, Y축에 last_value(view_count)를 설정한 막대 차트를 사용하세요. 이를 통해 각 대시보드의 현재 일일 조회수를 확인할 수 있습니다.
• 시간에 따른 조회수 변화: X축에 captured_at을, Y축에 last_value(view_count)를 설정하고 dashboard_name으로 구분한 선형 차트를 사용하세요. 워크플로우를 실행할 때마다 새로운 문서가 추가되므로 중복 합산 대신 'Last value' 집계를 사용하여 시간 버킷당 최종 수치를 가져옵니다.
• 현재 스냅샷: 가장 최근의 captured_at 데이터를 사용하는 데이터 테이블을 만들어 모든 대시보드의 최신 조회수를 표시하세요.

각 워크플로우 실행 시마다 새 문서가 생성되므로 시간 범위를 필터링하여 특정 기간의 활동을 분석하거나 주간 단위로 비교할 수 있습니다. 또한 대시보드 조회수가 임계값 아래로 떨어질 때 알림을 구축할 수 있습니다.

결론

Elastic Workflows는 이러한 주기적인 데이터 수집에 매우 적합합니다. 데이터 소스(Kibana API)와 대상(Elasticsearch)이 모두 네이티브로 연결되어 있어 자격 증명을 별도로 관리할 필요가 없기 때문입니다. 워크플로우 엔진이 kibana.request 및 elasticsearch.request단계의 인증을 자동으로 처리하므로 사용자는 로직만 작성하면 됩니다.

리소스

• Elastic Workflows
• Kibana API

Elasticsearch는 늦게 도착한 메트릭을 거부하고 있었습니다. 이로 인해 파이프라인이 밀리기 시작했고, 더 많은 데이터가 늦게 도착하면서 거부가 더욱 늘어나게 되었습니다. 결국 파이프라인은 완전히 멈춰 섰습니다.

스냅샷에서 복원하고, 데이터를 다시 인덱싱하고, 수집 파이프라인을 다시 설계하여 복구해야 했습니다.

근본 원인은 인덱스 수명 주기 관리(ILM) 자체가 아니라, 시계열 데이터 스트림(TSDS)과 이를 통해 시간 제한 백킹(backing) 인덱스를 강제하는 방식에 있었습니다.

TSDS는 메트릭의 저장 공간 요구 사항을 40–70% 줄일 수 있지만, TSDS를 효율적으로 만드는 아키텍처 변경으로 인해 시간이 지남에 따라 인덱스의 동작 방식도 달라집니다. 이러한 변화는 ILM 정책을 설계하거나 수집 파이프라인에서 데이터가 늦게 도착할 수 있는 상황에서 중요합니다.

요약

TSDS를 사용하는 경우:

• 백킹 인덱스는 특정 시간 범위에 해당하는 문서만 허용합니다.
• 인덱스가 cold 또는 frozen으로 이동한 뒤 데이터가 늦게 도착하면, Elasticsearch는 해당 문서를 수용하지 않거나(설정된 경우) failure store로 라우팅합니다.

설계 규칙:

warm_min_age > rollover_max_age + maximum_expected_lateness

시계열 데이터 스트림이란 무엇인가요?

시계열 데이터 스트림(TSDS)은 메트릭 데이터에 최적화된 특수한 데이터 스트림입니다. 데이터는 관련 문서가 동일한 샤드 내에 위치하도록 라우팅되어 쿼리 및 검색에 최적화됩니다. Elasticsearch가 이를 수행하는 방법은 다음과 같습니다.

각 문서에는 다음이 포함됩니다.

• 타임스탬프.
• 시계열을 식별하는 dimension 필드.
• 측정값을 나타내는 metric 필드.

예를 들면 다음과 같습니다.

• 호스트당 CPU 사용량.
• 서비스별 요청 지연 시간.
• 센서별 온도 측정값.

dimensions는 측정하고자 하는 대상을 식별하는 반면, metrics는 시간에 따라 변하는 값을 나타냅니다.

dimensions

dimensions는 측정되는 엔티티를 설명합니다.

예:

host.name
service.name
container.id

다음과 같이 매핑에서 정의합니다.

time_series_dimension: true

metrics

metrics는 숫자 값을 나타내며 다음을 사용하여 정의됩니다.

time_series_metric

일반적인 metric 유형:

• gauge: 오르내리는 값.
• counter: 재설정될 때까지 증가하는 값.

Elastic Agent는 주로 메트릭과 로그 데이터를 수집하므로, TSDS 인덱스를 직접 활성화하지 않은 경우에도 클러스터에 해당 인덱스가 여전히 존재할 수 있습니다.

_tsid 필드

Elasticsearch는 내부적으로 dimension 필드로부터 _tsid 값을 생성합니다. 이를 통해 동일한 dimensions를 가진 문서는 동일한 샤드로 라우팅되어 다음을 개선합니다.

• 압축.
• 쿼리 로컬리티.
• 집계 성능.

주요 차이점: 시간 제한 백킹 인덱스

기존 데이터 스트림은 항상 쓰기 인덱스라고 하는 가장 최근의 백킹 인덱스에 기록되지만, TSDS는 다르게 동작합니다.

각 TSDS 백킹 인덱스에는 정의된 시간 구간이 있으며 해당 구간에 해당하는 @timestamp 값을 가진 문서만 허용합니다.

GET _data_stream/my-metrics-data-stream


     "index_mode": "time_series",
     "time_series": {
       "temporal_ranges": [
         {
           "start": "2026-01-15T14:35:50.000Z",
           "end": "2026-03-16T11:34:40.000Z"
         }
       ]
     }

문서가 인덱싱되면 Elasticsearch는 해당 타임스탬프를 담당하는 백킹 인덱스로 라우팅하는데, 이는 기존의 인덱스와 달리 TSDS가 여러 백킹 인덱스에 동시에 쓰기를 수행할 수 있음을 의미합니다.

그 예는 다음과 같습니다.

• 실시간 데이터 → 최신 인덱스.
• 지연된 데이터 → 해당 기간을 포함하는 이전 인덱스.

늦게 도착하는 데이터를 위한 설계

실제 수집 파이프라인은 메트릭을 제시간에 완벽하게 전달하는 경우가 거의 없습니다. 메트릭은 네트워크 장애, 백로그, 배치 수집, 엣지 디바이스의 연결 끊김 등으로 인해 지연될 수 있으며, 다시 연결되면 밀린 데이터를 시작합니다.

기존 인덱스는 이러한 지연을 조용히 흡수하지만, TSDS는 그렇지 않습니다.

문서의 타임스탬프가 쓰기 가능한 백킹 인덱스의 범위를 벗어나면 Elasticsearch가 이를 거부하므로, ILM 정책은 늦게 도착하는 데이터를 반드시 고려해야 합니다.

핵심 제약 조건

백킹 인덱스는 지연 데이터를 수용할 수 있을 만큼 충분히 오랫동안 쓰기 가능 상태를 유지해야 합니다.

실제로는 다음과 같다.

time_until_readonly > maximum_expected_lateness

ILM은 롤오버 시점부터 인덱스 나이를 측정하므로, 운영 규칙은 다음과 같습니다.

warm_or_cold_min_age > rollover_max_age + maximum_expected_lateness

예를 들어, 메트릭이 최대 6시간 늦게 도착할 수 있는 경우 인덱스는 롤오버 후 최소 6시간 동안 쓰기 가능한 상태로 유지되어야 합니다.

이러한 제약 조건을 고려하지 못한 것이 바로 앞서 설명한 데이터 수집 실패의 원인이었습니다. 늦게 도착한 데이터는 이전 인덱스로 전달됐는데, 해당 인덱스는 이미 cold 티어에 있어서 쓰기가 차단된 상태였습니다.

거부된 문서를 처리하는 방법

TSDS가 문서를 거부하면 Elasticsearch는 오류를 반환하는데, 이는 타임스탬프가 쓰기 가능한 인덱스 범위 내에 속하지 않음을 의미합니다. 데이터 수집 파이프라인이 이 오류를 어떻게 처리하느냐에 따라 데이터 손실이 발생할 수도 있고, 수집이 중단될 수도 있습니다.

거부된 문서를 처리하는 주요 메커니즘은 failure store입니다.

failure store(Elasticsearch 9.1 이상에서 권장)

Elasticsearch 9.1에서는 failure store를 도입하여 거부된 문서를 자동으로 수집합니다. Elasticsearch는 클라이언트에 오류를 반환하는 대신 실패한 문서를 데이터 스트림 내부의 전용 failure 인덱스에 기록합니다.

다음을 사용하여 오류를 검사할 수 있습니다:

GET metrics-myapp::failures/_search

failure store를 사용하면 수집 파이프라인이 거부 오류로 인해 막히는 것을 방지하면서, 실패한 데이터를 분석 또는 재인덱싱을 위해 보존할 수 있습니다.

거부 관련 문제 모니터링

늦게 도착하는 문제는 일반적으로 수집 이상 징후로 먼저 나타납니다. 다음과 같은 현상으로 먼저 감지될 수 있습니다.

• 인덱싱 속도의 급격한 감소.
• 거부된 문서 수의 급증.
• failure store 항목 수 증가.
• 파이프라인 입력과 출력 개수 간의 불일치.

이러한 신호를 기반으로 한 알림을 통해 운영자는 파이프라인이 중단되기 전에 문제를 감지할 수 있습니다. 워크플로우, 머신 러닝 작업 등 다양한 메커니즘을 활용해 탐지 및 알림을 자동화할 수 있습니다.

TSDS + ILM 마이그레이션 체크리스트

TSDS로 메트릭 클러스터를 마이그레이션하거나, ILM 계층화를 도입하거나, 메트릭이 기본적으로 TSDS인 Elasticsearch 버전으로 업그레이드하는 경우, 먼저 다음 항목을 검토하세요.

1. 수집 지연 시간 측정

ILM 정책을 변경하기 전에 다음 사항을 확인하세요.

• 정상적인 수집 지연 시간.
• 인시던트 상황에서의 최대 지연.
• 배치 파이프라인으로 인한 지연.

ILM 설계는 현실적으로 발생할 수 있는 최대 지연을 반드시 고려해야 합니다.

2. 인덱스 시간 구간 확인

TSDS 백킹 인덱스를 확인합니다.

GET _data_stream/

다음을 확인하세요.

• time_series.start_time
• time_series.end_time

이러한 경계는 어떤 인덱스가 문서를 수용할 수 있는지를 결정합니다. 이러한 시간 구간을 이해하면 데이터가 어느 정도까지 지연될 수 있는지(거부되기 전까지)를 판단하는 데 도움이 됩니다.

3. 지연 데이터를 위한 hot 티어 크기 조정

백킹 인덱스는 지연 데이터를 처리할 수 있도록 충분한 기간 동안 쓰기 가능 상태를 유지해야 한다.

운영 규칙:

• warm_min_age > rollover_max_age + maximum_expected_lateness

메트릭이 6시간 늦게 도착할 수 있는 경우, 인덱스는 최소 6시간 동안 쓰기 가능 상태를 유지해야 한다는 점을 잊지 마세요.

4. 거부된 문서 처리 방식 결정

TSDS를 활성화하기 전에 전략을 선택하세요.

• failure store(Elasticsearch 9.1 이상에서 권장)
• Logstash dead letter queue.
• 지연 데이터 처리를 위한 대체 인덱스.
• 제한적인 데이터 손실 허용.

5. 데이터 수집 상태 모니터링

다음 항목에 대한 알림을 추가하세요.

• 인덱싱 속도 하락.
• 거부된 문서.
• failure store 증가
• 파이프라인 입력/출력 불일치.

늦게 도착하는 데이터 문제는 종종 수집 이상 징후로 먼저 나타납니다.

요약

시계열 데이터 스트림은 메트릭 워크로드의 스토리지와 성능을 크게 개선하지만, 중요한 아키텍처 변경을 수반합니다. 백킹 인덱스는 시간 기반으로 제한되며, 이는 ILM의 동작 방식에 영향을 미칩니다.

TSDS를 사용하는 경우:

• 인덱스는 지연 데이터를 수용할 수 있을 만큼 충분히 오랫동안 쓰기 가능 상태를 유지해야 합니다.
• 수집 파이프라인은 거부된 문서를 안정적으로 처리해야 합니다.

기억해야 할 핵심 규칙은 다음과 같습니다:

warm_min_age > rollover_max_age + maximum_expected_lateness

이 제약 조건을 중심으로 ILM 정책을 설계하면 TSDS는 메트릭 워크로드에 매우 효과적으로 작동합니다.

하지만 이를 무시하면 수집 파이프라인이 이러한 시간 경계를 직접 겪으며 문제를 발견하게 될 수 있습니다.

첫 번째 쿼리

먼저 Elasticsearch 인덱스에 맵핑되는 일반 CLR 객체(POCO)를 정의합니다. 속성 이름은 표준 System.Text.Json 속성(예: [JsonPropertyName]) 또는 구성된 JsonNamingPolicy을(를) 통해 ES|QL 열 이름으로 확인됩니다. 클라이언트의 나머지 부분에 적용되는 소스 직렬화 규칙이 여기에도 동일하게 적용됩니다.

using System.Text.Json.Serialization;

public class Product
{
    [JsonPropertyName("product_id")]
    public string Id { get; set; }

    public string Name { get; set; }

    public string Brand { get; set; }

    [JsonPropertyName("price_usd")]
    public double Price { get; set; }

    [JsonPropertyName("in_stock")]
    public bool InStock { get; set; }
}

유형이 지정되면 쿼리는 다음과 같습니다.

var minPrice = 100.0;
var brand = "TechCorp";

await foreach (var product in client.Esql.QueryAsync(q => q
    .From("products")
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10)))
{
    Console.WriteLine($"{product.Name}: ${product.Price}");
}

제공자는 이를 다음과 같은 ES|QL로 변환합니다.

FROM products
| WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand)
| SORT price_usd DESC
| LIMIT 10

참고할 만한 몇 가지 세부 사항은 다음과 같습니다.

• 속성 이름 확인: p.Price은(는) [JsonPropertyName] 속성 때문에 price_usd이(가) 되고, p.Brand은(는) 기본 camelCase 명명 정책에 따라 brand이(가) 됩니다.
• 매개변수 캡처: C# 변수 minPrice 및 brand 은(는) 명명된 매개변수(?minPrice, ?brand)(으)로 캡처됩니다. 이러한 변수는 JSON 페이로드에서 쿼리 스트링과 별도로 전송되므로 인젝션을 방지하고 서버 측 쿼리 계획 캐싱을 활성화합니다.
• 스트리밍: QueryAsync<T> 은(는)IAsyncEnumerable<T>을(를) 반환합니다. 행은 Elasticsearch에서 도착하는 대로 한 번에 하나씩 구체화됩니다.

다음과 같이 생성된 쿼리와 해당 매개변수를 실행하지 않고도 확인할 수 있습니다.

var query = client.Esql.CreateQuery()
    .Where(p => p.InStock && p.Price >= minPrice && p.Brand == brand)
    .OrderByDescending(p => p.Price)
    .Take(10);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE (in_stock == true AND price_usd >= 100) | SORT price_usd DESC | LIMIT 10

Console.WriteLine(query.ToEsqlString(inlineParameters: false));
// FROM products | WHERE (in_stock == true AND price_usd >= ?minPrice AND brand == ?brand) | SORT price_usd DESC | LIMIT 10

var parameters = query.GetParameters();
// { "minPrice": 100.0, "brand": "TechCorp" }

작동 원리: LINQ 핵심 개념 되짚어보기

LINQ 제공자를 가능하게 하는 메커니즘은 IEnumerable<T>와(과) IQueryable<T>의 구분입니다.

IEnumerable<T> 에 대해.Where(p => p.Price > 100) 을(를) 호출하면 lambda는 런타임이 프로세스 중에 실행하는 일반 델리게이트인 Func<Product, bool> (으)로 컴파일됩니다. 이것이 LINQ-to-Objects입니다.

IQueryable<T>에서 동일한 메서드를 호출하면 C# 컴파일러는 lambda를Expression<Func<Product, bool>> (으)로 래핑합니다. 이는 실행 가능한 형태가 아닌 코드의 구조를 나타내는 데이터 구조입니다. 표현식 트리는 런타임에 검사, 분석 및 다른 언어로 변환될 수 있습니다.

// IEnumerable: the lambda is a compiled delegate
IEnumerable local = products.Where(p => p.Price > 100);

// IQueryable: the lambda is an expression tree, a data structure
IQueryable remote = queryable.Where(p => p.Price > 100);

IQueryProvider 인터페이스는 확장 지점입니다. 모든 제공자는 CreateQuery<T> 및 Execute<T>을(를) 구현하여 이러한 표현식 트리를 대상 언어로 변환할 수 있습니다. Entity Framework는 이를 사용하여 SQL을 출력합니다. LINQ to ES|QL 제공자는 이를 사용하여 ES|QL을 출력합니다.

위 쿼리의 표현식 트리는 다음과 같습니다.

예제 쿼리의 표현식 트리입니다.

Take 은(는)OrderByDescending 을(를) 감싸고, 이는 Where 을(를) 감싸고, 이는 From 을(를) 감싸고, 이는 EsqlQueryable<Product> 상수를 감싸는 식으로 트리가 안쪽에서 바깥쪽으로 중첩됩니다. Where 술어는 그 자체로 &&, >=, == 연산자에 대한 BinaryExpression 노드의 하위 트리이며, MemberExpression 은(는) 속성 액세스 및 minPrice 및 brand 변수에 대한 클로저 캡처를 위한 리프입니다. 이는 제공자가 최종 ES|QL을 생성하기 위해 거치는 데이터 구조입니다.

작동 원리 살펴보기: 변환 파이프라인

LINQ 표현식에서 쿼리 결과에 이르는 경로는 다음과 같이 6단계 파이프라인을 따릅니다.

변환 파이프라인 개요.

1. 표현식 트리 캡처

.Where(), .OrderBy(), .Take() 및 기타 연산자를 IQueryable<T>에 연결하면 표준 LINQ 인프라가 표현식 트리를 구축합니다. EsqlQueryable<T>은(는) IQueryable<T>을(를) 구현하고 EsqlQueryProvider에 위임합니다.

2. 번역

쿼리가 실행될 때(열거, ToList() 호출 또는 await foreach) 사용), EsqlExpressionVisitor은(는) 표현식 트리를 안쪽에서 바깥쪽으로 탐색합니다. 각 LINQ 메서드 호출을 전문 방문자에게 전달합니다.

변환 과정에서 표현식에서 참조되는 C# 변수는 명명된 매개변수로 캡처됩니다.

3. 쿼리 모델

방문자는 스트링을 직접 생성하지 않습니다. 대신 QueryCommand 객체, 즉 불변의 중간 표현을 생성합니다. FromCommand, WhereCommand, SortCommand, LimitCommand은(는) 각각 하나의 ES|QL 처리 명령을 나타냅니다. 이들은 EsqlQuery 모델로 수집됩니다.

쿼리 모델 및 명령 패턴입니다.

이 중간 모델은 표현식 트리 및 출력 형식에서 모두 분리되어 있습니다. 형식을 지정하기 전에 검사하거나, 가로채거나(IEsqlQueryInterceptor을(를) 통해), 수정할 수 있습니다.

4. 형식 지정

EsqlFormatter 각 QueryCommand을(를) 순서대로 방문하여 최종 ES|QL 스트링을 생성합니다. 각 명령은 ES|QL이 처리 명령을 연결하는 데 사용하는 파이프(|) 연산자로 구분되어 한 줄로 표시됩니다. 특수 문자가 포함된 식별자는 백틱으로 자동 이스케이프 처리됩니다.

5. 실행

형식화된 ES|QL 스트링과 캡처된 매개변수는 JSON 페이로드로 Elasticsearch의 /_query 엔드포인트로 전송됩니다. IEsqlQueryExecutor 인터페이스는 계층형 패키지 아키텍처가 적용되는 전송 계층을 추상화합니다.

6. 구체화

EsqlResponseReader 전체 결과 세트를 메모리에 버퍼링하지 않고 JSON 응답을 스트리밍합니다. 쿼리당 한 번씩 미리 계산되는 ColumnLayout 트리는 플랫 ES|QL 열 이름(예: address.street, address.city)을(를) 중첩된 POCO 속성에 맵핑합니다. 각 행은 T 인스턴스로 조립되어 IEnumerable<T> 또는 IAsyncEnumerable<T>을(를) 통해 한 번에 하나씩 제공됩니다.

계층 아키텍처

LINQ to ES|QL 기능은 다음과 같이 세 개의 패키지로 나뉩니다.

패키지 아키텍처.
Elastic.Esql 은(는) 순수 변환 엔진입니다. HTTP 종속성이 전혀 없으며 표현식 방문자, 쿼리 모델, 포맷터 및 응답 판독기를 포함합니다. Elasticsearch 연결 없이 독립적으로 사용하여 ES|QL 쿼리를 구축하고 검사할 수 있어 테스트, 쿼리 로깅 또는 자체 실행 계층을 구축하는 데 유용합니다.

// Translation-only: no Elasticsearch connection needed
var provider = new EsqlQueryProvider();
var query = new EsqlQueryable(provider)
    .From("products")
    .Where(p => p.InStock)
    .OrderByDescending(p => p.Price);

Console.WriteLine(query.ToEsqlString());
// FROM products | WHERE in_stock == true | SORT price_usd DESC

Elastic.Clients.Esql 경량 독립형 ES|QL 클라이언트입니다. Elastic.Transport을(를) 통해 Elastic.Esql 위에 HTTP 실행 기능을 추가합니다. 애플리케이션에 ES|QL만 필요하고 다른 Elasticsearch API는 필요하지 않은 경우, 이것이 최소한의 종속성 옵션입니다.

Elastic.Clients.Elasticsearch 완전한 Elasticsearch .NET 클라이언트입니다. 이 또한 Elastic.Esql을(를) 기반으로 하며 client.Esql 네임스페이스를 통해 LINQ 제공자를 노출합니다. 대부분의 애플리케이션에 권장되는 진입점입니다.

두 실행 계층 패키지 모두 변환과 전송을 연결하는 전략 인터페이스인 IEsqlQueryExecutor의 자체 구현을 제공합니다.

세 패키지 모두 소스에서 생성된 JsonSerializerContext와(과) 함께 사용할 경우 Native AOT와 호환됩니다. 전체 클라이언트에 대한 자세한 내용은 Native AOT 설명서를 확인하세요.

기본을 넘어서

위의 예에서는 필터링, 정렬 및 페이지 매김을 다뤘습니다. 공급자는 더 광범위한 작업을 지원합니다.

집계

GroupBySelect의 집계 함수와 결합하면 ES|QL STATS ... BY(으)로 변환됩니다.

var stats = client.Esql.Query(q => q
    .GroupBy(p => p.Brand)
    .Select(g => new
    {
        Brand = g.Key,
        Count = g.Count(),
        AvgPrice = g.Average(p => p.Price),
        MaxPrice = g.Max(p => p.Price)
    }));

// -> FROM products | STATS COUNT(*), AVG(price_usd), MAX(price_usd) BY brand

프로젝션

Select익명 유형은 EVAL, KEEP, RENAME 명령을 생성합니다.

var query = client.Esql.CreateQuery()
    .Select(p => new { ProductName = p.Name, p.Price, p.InStock });

// -> FROM products | KEEP name, price_usd, in_stock | RENAME name AS ProductName

풍부한 함수 라이브러리

EsqlFunctions 클래스를 통해 날짜/시간, 스트링, 수학, IP, 패턴 매칭 및 스코어링을 포함한 80개 이상의 ES|QL 함수를 사용할 수 있습니다. 다음과 같이 표준 Math.* 및 string.* 메서드도 변환됩니다.

.Where(p => p.Name.Contains("Pro"))       // -> WHERE name LIKE "*Pro*"
.Where(p => EsqlFunctions.CidrMatch(      // -> WHERE CIDR_MATCH(ip, "10.0.0.0/8")
    p.IpAddress, "10.0.0.0/8"))

조회 조인

교차 인덱스 조회는 ES|QL LOOKUP JOIN(으)로 변환됩니다.

var enriched = client.Esql.Query(q => q
    .LookupJoin(
        "category-lookup-index",
        product => product.Id,
        category => category.CategoryId,
        (product, category) => new { product.Name, category!.CategoryLabel }));

원시 ES|QL 이스케이프 해치

LINQ 제공자가 아직 지원하지 않는 ES|QL 기능의 경우 다음과 같이 원시 조각을 추가할 수 있습니다.

var results = client.Esql.Query(q => q
    .Where(p => p.InStock)
    .RawEsql("| EVAL discounted = price_usd * 0.9"));

서버 측 비동기 쿼리

장기 실행 쿼리의 경우 다음과 같이 서버에서 백그라운드 처리를 위해 제출하세요.

await using var asyncQuery = await client.Esql.SubmitAsyncQueryAsync(
    q => q.Where(p => p.InStock),
    asyncQueryOptions: new EsqlAsyncQueryOptions
    {
        WaitForCompletionTimeout = TimeSpan.FromSeconds(5),
        KeepAlive = TimeSpan.FromMinutes(10)
    });

await asyncQuery.WaitForCompletionAsync();
await foreach (var product in asyncQuery.AsAsyncEnumerable())
    Console.WriteLine(product.Name);

서버 측 비동기 쿼리는 일반적인 시간 초과 임계값을 초과할 수 있는 장기 실행 분석 쿼리/대규모 데이터 세트 처리에 특히 유용합니다. 또한 엄격한 HTTP 시간 초과를 적용하는 로드 밸런서, API 게이트웨이 또는 프록시가 있는 시간 초과에 민감한 환경에서도 유용합니다. 비동기 쿼리는 제출과 결과 검색을 분리하여 연결 끊김을 방지합니다.

시작하기

LINQ to ES|QL은 다음 버전부터 사용 가능합니다.

• Elastic.Clients.Elasticsearch v9.3.4 (9.x 브랜치)
• Elastic.Clients.Elasticsearch v8.19.18 (8.x 브랜치)

NuGet에서 설치:

dotnet add package Elastic.Clients.Elasticsearch

진입점은 client.Esql 에 있습니다.

쿼리 옵션, 다중 필드 액세스, 중첩 객체, 다중 값 필드 처리 등 전체 기능에 대한 참조는 LINQ to ES|QL 설명서를 확인하세요.

결론

LINQ to ES|QL은 C# LINQ의 모든 표현력을 Elasticsearch의 ES|QL 쿼리 언어로 제공하여 쿼리 스트링을 직접 작성하지 않고도 강력한 형식의 조합 가능한 쿼리를 작성할 수 있도록 해줍니다. 자동 매개변수 캡처, 스트리밍 구체화, 그리고 독립 실행형 변환부터 전체 Elasticsearch 클라이언트까지 확장 가능한 계층형 패키지 아키텍처를 통해 모든 규모의 .NET 애플리케이션에 자연스럽게 통합됩니다. 최신 클라이언트를 설치하고 LINQ 표현식에서 인덱스를 지정하기만 하면 나머지는 제공자가 처리합니다.

이 글에서는 사용자 지정 Elasticsearch MCP 서버 구축의 장점을 살펴보고, Elasticsearch를 LLM 기반 애플리케이션에 연결하는 TypeScript로 서버를 생성하는 방법을 보여드리겠습니다.

사용자 지정 Elasticsearch MCP 서버를 구축해야 하는 이유는 무엇입니까?

Elastic은 MCP 서버에 대한 몇 가지 대안을 제공합니다.

• Elasticsearch 9.2 이상 버전용 Elastic Agent Builder MCP 서버
• 구버전용 Elasticsearch MCP 서버(Python)

MCP 서버가 Elasticsearch와 상호 작용하는 방식을 더 세밀하게 제어하고 싶다면, 직접 사용자 지정 서버를 구축하여 요구 사항에 딱 맞게 최적화할 수 있는 유연성을 확보할 수 있습니다. 예를 들어, Agent Builder의 MCP 엔드포인트는 Elasticsearch 쿼리 언어(ES|QL) 쿼리로 제한되지만, 사용자 지정 서버를 사용하면 전체 쿼리 DSL을 사용할 수 있습니다. 또한 결과를 LLM으로 전달되기 전에 결과의 서식을 지정하는 방법을 제어할 수 있으며, 이번 튜토리얼에서 다룰 OpenAI 기반 요약 기능과 같은 추가적인 처리 단계를 통합할 수도 있습니다.

이 글을 마칠 때쯤이면, Elasticsearch 인덱스에 저장된 정보를 검색하고, 요약하며, 인용을 제공하는 TypeScript로 된 MCP 서버를 갖게 됩니다. 검색에는 Elasticsearch를, 요약 및 인용 생성에는 OpenAI gpt-4o-mini 모델을 사용하며, 사용자 쿼리를 받고 응답을 제공하는 MCP 클라이언트와 UI로는 Claude Desktop을 사용할 것입니다. 최종적으로 엔지니어가 조직 내 기술 문서 전반에서 모범 사례를 발견하고 종합할 수 있도록 돕는 내부 지식 어시스턴트를 구축하게 됩니다.

필수 구성 요소:

• Node.js 20+
• Elasticsearch
• OpenAI API 키
• Claude Desktop

MCP란 무엇입니까?

MCP는 Anthropic에서 만든 오픈 표준으로, LLM과 Elasticsearch와 같은 외부 시스템 간에 안전한 양방향 연결을 제공합니다. MCP의 현황에 대한 자세한 내용은 이 글에서 확인할 수 있습니다.

MCP 환경은 광범위한 사용 사례를 지원하는 서버들이 등장하며 매일 진화하고 있습니다. 게다가, 이 글에서 보여 드릴 것처럼 자신만의 맞춤형 MCP 서버를 구축하는 것도 매우 쉽습니다.

MCP 클라이언트

사용 가능한 MCP 클라이언트 목록은 매우 방대하며, 각 클라이언트에는 저마다의 특징과 제한 사항이 있습니다. 단순함과 대중성을 고려하여 Claude Desktop을 MCP 클라이언트로 사용하겠습니다. Claude Desktop은 사용자가 자연어로 질문을 던지는 채팅 인터페이스 역할을 하며, MCP 서버에 노출된 도구를 자동으로 호출하여 문서를 검색하고 요약을 생성합니다.

Elasticsearch MCP 서버 생성하기

TypeScript SDK를 사용하면, 사용자 쿼리 입력을 기반으로 Elasticsearch 데이터를 쿼리하는 방법을 이해하는 서버를 쉽게 만들 수 있습니다.

이 글에서는 Elasticsearch MCP 서버를 Claude Desktop 클라이언트와 통합하는 단계를 설명합니다.

1. Elasticsearch용 MCP 서버를 구성합니다.
2. MCP 서버를 Claude Desktop에 로드합니다.
3. 테스트해 보세요.

Elasticsearch용 MCP 서버 구성

시작하려면 Node 애플리케이션을 초기화하십시오:

npm init -y

이렇게 하면 package.json 파일이 생성되며, 이를 통해 이 애플리케이션에 필요한 의존성을 설치하기 시작할 수 있습니다.

npm install @elastic/elasticsearch @modelcontextprotocol/sdk openai zod && npm install --save-dev ts-node @types/node typescript

• @elastic/elasticsearch 패키지를 통해 Elasticsearch Node.js 라이브러리에 액세스할 수 있습니다.
• @modelcontextprotocol/sdk는 MCP 서버 생성 및 관리, 도구 등록, MCP 클라이언트와의 통신 처리를 위한 핵심 도구를 제공합니다.
• openai를 사용하면 OpenAI 모델과 상호 작용하여 요약이나 자연어 응답을 생성할 수 있습니다.
• zod는 각 도구의 입력 및 출력 데이터에 대해 구조화된 스키마를 정의하고 검증하는 것을 돕습니다.

ts-node, @types/node, typescript 는 개발 중에 코드의 타입을 지정하고 스크립트를 컴파일하는 데 사용됩니다.

데이터셋 설정

Claude Desktop이 MCP 서버를 통해 쿼리할 수 있는 데이터를 제공하기 위해, 가상의 내부 지식 기반 데이터 세트를 사용하겠습니다. 이 데이터 세트의 문서는 다음과 같습니다.

{
    "id": 5,
    "title": "Logging Standards for Microservices",
    "content": "Consistent logging across microservices helps with debugging and tracing. Use structured JSON logs and include request IDs and timestamps. Avoid logging sensitive information. Centralize logs in Elasticsearch or a similar system. Configure log rotation to prevent storage issues and ensure logs are searchable for at least 30 days.",
    "tags": ["logging", "microservices", "standards"]
}

데이터를 수집하기 위해, Elasticsearch에 인덱스를 생성하고 데이터 세트를 로드하는 스크립트를 준비했습니다. 여기서 확인하실 수 있습니다.

MCP 서버

index.ts(이)라는 이름의 파일을 생성하고, 의존성을 가져오고 환경 변수를 처리하기 위해 다음 코드를 추가하세요.

// index.ts
import { z } from "zod";
import { Client } from "@elastic/elasticsearch";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import OpenAI from "openai";

const ELASTICSEARCH_ENDPOINT =
  process.env.ELASTICSEARCH_ENDPOINT ?? "http://localhost:9200";
const ELASTICSEARCH_API_KEY = process.env.ELASTICSEARCH_API_KEY ?? "";
const OPENAI_API_KEY = process.env.OPENAI_API_KEY ?? "";
const INDEX = "documents";

또한, Elasticsearch와 OpenAI 호출을 처리할 클라이언트들을 초기화해 보겠습니다.

const openai = new OpenAI({
  apiKey: OPENAI_API_KEY,
});

const _client = new Client({
  node: ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: ELASTICSEARCH_API_KEY,
  },
});

구현을 더 견고하게 만들고 입력 및 출력 데이터의 구조를 보장하기 위해, zod(을)를 사용하여 스키마를 정의하겠습니다. 이를 통해 런타임에 데이터를 검증하고, 오류를 조기에 발견하며, 도구의 응답을 프로그램 방식으로 더 쉽게 처리할 수 있습니다.

const DocumentSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
});

const SearchResultSchema = z.object({
  id: z.number(),
  title: z.string(),
  content: z.string(),
  tags: z.array(z.string()),
  score: z.number(),
});

type Document = z.infer;
type SearchResult = z.infer;

구조화된 출력을 자세히 알아보려면 여기를 참조하세요.

이제 MCP 서버를 초기화해 보겠습니다.

const server = new McpServer({
  name: "Elasticsearch RAG MCP",
  description:
    "A RAG server using Elasticsearch. Provides tools for document search, result summarization, and source citation.",
  version: "1.0.0",
});

MCP 도구 정의

모든 구성이 완료되면, MCP 서버가 외부에 제공할 도구를 작성하기 시작할 수 있습니다. 이 서버는 두 가지 도구를 외부에 제공합니다.

• search_docs: 전체 텍스트 검색을 사용하여 Elasticsearch에서 문서를 검색합니다.
• summarize_and_cite: 사용자의 질문에 답하기 위해, 이전에 검색된 문서들로부터 정보를 요약하고 종합합니다. 이 도구는 또한 출처 문서를 참조하는 인용 정보를 추가합니다.

이 도구들은 함께 작동하여 간단한 '검색 후 요약' 워크플로우를 형성합니다. 하나의 도구가 관련 문서를 가져오면, 다른 도구가 해당 문서들을 바탕으로 인용구가 포함된 요약 응답을 생성하는 방식입니다.

도구 응답 형식

각 도구는 임의의 입력 매개변수를 허용할 수 있지만, 다음과 같은 구조로 응답해야 합니다.

• 내용: 비정형 형식으로 된 도구의 응답입니다. 이 필드는 일반적으로 텍스트, 이미지, 오디오, 링크 또는 임베딩을 반환하는 데 사용됩니다. 이 애플리케이션의 경우 도구가 생성한 정보를 포함한 서식 있는 텍스트를 반환하는 데 사용됩니다.
• structuredContent: 각 도구의 결과를 구조화된 형식으로 제공하기 위해 사용되는 선택적 반환 값입니다. 이는 프로그램 방식의 처리에 유용합니다. 비록 이 MCP 서버에서는 사용되지 않지만, 다른 도구를 개발하거나 결과를 프로그램 방식으로 처리하고자 할 때 유용하게 활용될 수 있습니다.

그 구조를 염두에 두고, 각 도구에 대해 자세히 살펴보겠습니다.

Search_docs 도구

이 도구는 사용자의 쿼리를 기반으로 가장 관련성 높은 문서들을 검색하기 위해 Elasticsearch 인덱스에서 전체 텍스트 검색을 수행합니다. 또한 주요 일치 항목을 강조하고, 연관성 점수와 함께 빠른 개요를 제공합니다.

server.registerTool(
  "search_docs",
  {
    title: "Search Documents",
    description:
      "Search for documents in Elasticsearch using full-text search. Returns the most relevant documents with their content, title, tags, and relevance score.",
    inputSchema: {
      query: z
        .string()
        .describe("The search query terms to find relevant documents"),
      max_results: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of results to return"),
    },
    outputSchema: {
      results: z.array(SearchResultSchema),
      total: z.number(),
    },
  },
  async ({ query, max_results }) => {
    if (!query) {
      return {
        content: [
          {
            type: "text",
            text: "Query parameter is required",
          },
        ],
        isError: true,
      };
    }

    try {
      const response = await _client.search({
        index: INDEX,
        size: max_results,
        query: {
          bool: {
            must: [
              {
                multi_match: {
                  query: query,
                  fields: ["title^2", "content", "tags"],
                  fuzziness: "AUTO",
                },
              },
            ],
            should: [
              {
                match_phrase: {
                  title: {
                    query: query,
                    boost: 2,
                  },
                },
              },
            ],
          },
        },
        highlight: {
          fields: {
            title: {},
            content: {},
          },
        },
      });

      const results: SearchResult[] = response.hits.hits.map((hit: any) => {
        const source = hit._source as Document;

        return {
          id: source.id,
          title: source.title,
          content: source.content,
          tags: source.tags,
          score: hit._score ?? 0,
        };
      });

      const contentText = results
        .map(
          (r, i) =>
            `[${i + 1}] ${r.title} (score: ${r.score.toFixed(
              2,
            )})\n${r.content.substring(0, 200)}...`,
        )
        .join("\n\n");

      const totalHits =
        typeof response.hits.total === "number"
          ? response.hits.total
          : (response.hits.total?.value ?? 0);

      return {
        content: [
          {
            type: "text",
            text: `Found ${results.length} relevant documents:\n\n${contentText}`,
          },
        ],
        structuredContent: {
          results: results,
          total: totalHits,
        },
      };
    } catch (error: any) {
      console.log("Error during search:", error);

      return {
        content: [
          {
            type: "text",
            text: `Error searching documents: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

We configure fuzziness: “AUTO” to have a variable typo tolerance based on the length of the token that’s being analyzed. We also set title^2 to increase the score of the documents where the match happens on the title 필드.

summarize_and_cite 도구

이 도구는 이전 검색에서 가져온 문서들을 바탕으로 요약을 생성합니다. 사용자의 질문에 답하기 위해 OpenAI의 gpt-4o-mini 모델을 사용하여 가장 관련성 높은 정보를 종합하며, 검색 결과에서 직접 도출된 응답을 제공합니다. 요약과 더불어, 사용된 출처 문서들에 대한 인용 메타데이터도 함께 반환합니다.

server.registerTool(
  "summarize_and_cite",
  {
    title: "Summarize and Cite",
    description:
      "Summarize the provided search results to answer a question and return citation metadata for the sources used.",
    inputSchema: {
      results: z
        .array(SearchResultSchema)
        .describe("Array of search results from search_docs"),
      question: z.string().describe("The question to answer"),
      max_length: z
        .number()
        .optional()
        .default(500)
        .describe("Maximum length of the summary in characters"),
      max_docs: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of documents to include in the context"),
    },
    outputSchema: {
      summary: z.string(),
      sources_used: z.number(),
      citations: z.array(
        z.object({
          id: z.number(),
          title: z.string(),
          tags: z.array(z.string()),
          relevance_score: z.number(),
        })
      ),
    },
  },
  async ({ results, question, max_length, max_docs }) => {
    if (!results || results.length === 0 || !question) {
      return {
        content: [
          {
            type: "text",
            text: "Both results and question parameters are required, and results must not be empty",
          },
        ],
        isError: true,
      };
    }

    try {
      const used = results.slice(0, max_docs);

      const context = used
        .map(
          (r: SearchResult, i: number) =>
            `[Document ${i + 1}: ${r.title}]\\n${r.content}`
        )
        .join("\n\n---\n\n");

      // Generate summary with OpenAI
      const completion = await openai.chat.completions.create({
        model: "gpt-4o-mini",
        messages: [
          {
            role: "system",
            content:
              "You are a helpful assistant that answers questions based on provided documents. Synthesize information from the documents to answer the user's question accurately and concisely. If the documents don't contain relevant information, say so.",
          },
          {
            role: "user",
            content: `Question: ${question}\\n\\nRelevant Documents:\\n${context}`,
          },
        ],
        max_tokens: Math.min(Math.ceil(max_length / 4), 1000),
        temperature: 0.3,
      });

      const summaryText =
        completion.choices[0]?.message?.content ?? "No summary generated.";

      const citations = used.map((r: SearchResult) => ({
        id: r.id,
        title: r.title,
        tags: r.tags,
        relevance_score: r.score,
      }));

      const citationText = citations
        .map(
          (c: any, i: number) =>
            `[${i + 1}] ID: ${c.id}, Title: "${c.title}", Tags: ${c.tags.join(
              ", ",
            )}, Score: ${c.relevance_score.toFixed(2)}`,
        )
        .join("\n");

      const combinedText = `Summary:\\n\\n${summaryText}\\n\\nSources used (${citations.length}):\\n\\n${citationText}`;

      return {
        content: [
          {
            type: "text",
            text: combinedText,
          },
        ],
        structuredContent: {
          summary: summaryText,
          sources_used: citations.length,
          citations: citations,
        },
      };
    } catch (error: any) {
      return {
        content: [
          {
            type: "text",
            text: `Error generating summary and citations: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }
);

마지막으로, stdio를 사용하여 서버를 시작해야 합니다. 이는 MCP 클라이언트가 서버의 표준 입력과 표준 출력 스트림을 읽고 씀으로써 통신하게 된다는 것을 의미합니다. stdio는 가장 단순한 전송 옵션이며, 클라이언트를 통해 하위 프로세스로 실행되는 로컬 MCP 서버에 적합합니다. 파일 끝에 다음 코드를 추가합니다.

const transport = new StdioServerTransport();
server.connect(transport);

이제 다음 명령어를 사용하여 프로젝트를 컴파일하십시오:

npx tsc index.ts --target ES2022 --module node16 --moduleResolution node16 --outDir ./dist --strict --esModuleInterop

이렇게 하면 dist 폴더가 생성되고, 그 안에 index.js 파일이 생성됩니다.

MCP 서버를 Claude Desktop에 로드

Claude Desktop에서 MCP 서버를 구성하려면 이 가이드를 따르세요. Claude 구성 파일에서 다음 값들을 설정해야 합니다.

{
  "mcpServers": {
    "elasticsearch-rag-mcp": {
      "command": "node",
      "args": [   "/Users/user-name/app-dir/dist/index.js"
      ],
      "env": {
        "ELASTICSEARCH_ENDPOINT": "your-endpoint-here",
        "ELASTICSEARCH_API_KEY": "your-api-key-here",
        "OPENAI_API_KEY": "your-openai-key-here"
      }
    }
  }
}

args 값은 dist 폴더 안에 있는 컴파일된 파일을 가리켜야 합니다. 또한 코드에 정의된 것과 똑같은 이름으로 구성 파일 내에 환경 변수를 설정해야 합니다.

테스트해 보기

각 도구를 실행하기 전에, 검색 및 도구를 클릭하여 도구들이 활성화되어 있는지 확인하세요. 여기에서 각 도구를 개별적으로 활성화하거나 비활성화할 수도 있습니다.

마지막으로 Claude Desktop 채팅에서 MCP 서버를 테스트하고 질문을 시작하십시오:

'인증 방법 및 역할 기반 액세스 제어에 관한 문서를 검색해 줘'라는 질문에 대해, search_docs 도구가 실행되어 다음과 같은 결과를 반환합니다.

Most Relevant Documents:
Access Control and Role Management (highest relevance) - This document covers role-based access control (RBAC) principles, including ensuring users only have necessary permissions, regular auditing of user roles, revoking inactive accounts, and implementing just-in-time access for sensitive operations.
User Authentication with OAuth 2.0 - This document explains OAuth 2.0 authentication, which enables secure delegated access without credential sharing. It covers configuring identity providers, token management with limited scope and lifetime, and secure storage of refresh tokens.
Container Security Guidelines - While primarily about container security, this document touches on access control aspects like running containers as non-root users and avoiding embedded credentials.
Incident Response Playbook - This mentions role assignment during incidents (incident commander, communications lead, etc.), which relates to access control in emergency scenarios.
Logging Standards for Microservices - This document includes guidance on avoiding logging sensitive information, which is relevant to authentication security.

응답 내용은 다음과 같습니다. '좋습니다! 인증 방식 및 역할 기반 액세스 제어에 관한 관련 문서 5개를 찾았습니다. 검색된 내용은 다음과 같습니다.'

도구 호출은 응답 페이로드의 일부로 소스 문서들을 반환하며, 이 문서들은 나중에 인용구를 생성하는 데 사용됩니다.

한 번의 상호 작용 내에서 여러 도구를 연결하여 사용할 수도 있습니다. 이 경우, Claude Desktop은 사용자의 질문을 분석한 뒤, 관련 문서를 가져오기 위해 먼저 search_docs(을)를 호출하고, 그 결과를 summarize_and_cite에 전달하여 최종 답변을 생성해야 한다고 판단합니다. 이 모든 과정은 별도의 사용자 프롬프트 없이 이루어집니다.

이 경우, '우리 시스템 전반의 인증 및 액세스 제어를 개선하기 위한 핵심 권장 사항이 뭐야? 참고 문헌 포함해 줘.'라는 쿼리에 대한 답변입니다. 다음과 같은 결과를 얻었습니다.

Based on the documentation, here are the main recommendations to improve authentication and access control across your systems:

Key Recommendations

1. Implement Role-Based Access Control (RBAC)
Ensure users have only the permissions necessary for their job functions. This principle of least privilege minimizes security risks by limiting access to what's truly needed. [1]

2. Regular Access Audits
Conduct regular audits of user roles and promptly revoke access for inactive accounts. This helps prevent unauthorized access from dormant or compromised accounts. [1]

3. Just-in-Time (JIT) Access
Implement just-in-time access for sensitive operations, where permissions are granted only when needed and for a limited duration. This reduces the attack surface by minimizing standing privileges. [1]

4. OAuth 2.0 for Secure Authentication
Use OAuth 2.0 to enable secure delegated access without sharing user credentials. This protocol allows third-party applications to access resources on behalf of users without exposing passwords. [2]

5. Token Security and Management
Configure your identity provider to issue tokens with limited scope and lifetime

Store refresh tokens securely
Validate access tokens consistently to maintain security [2]
References

Access Control and Role Management (Tags: security, access-control)
User Authentication with OAuth 2.0 (Tags: authentication, oauth)
These recommendations work together to create a defense-in-depth approach, where multiple security layers protect your systems from unauthorized access.

이전 단계와 마찬가지로, 이 질문에 대한 각 도구의 응답을 확인할 수 있습니다.

참고: 각 도구 사용 승인 여부를 묻는 하위 메뉴가 나타나면 항상 허용 또는 한 번 허용을 선택하십시오.

결론

MCP 서버는 로컬 및 원격 애플리케이션 모두를 위한 LLM 도구 표준화를 향한 중요한 진전을 의미합니다. 완전한 호환성을 구현하기 위해 아직 작업 중이지만, 이를 향해 빠르게 나아가고 있습니다.

이 글에서 Elasticsearch를 LLM 기반 애플리케이션에 연결하는 사용자 지정 MCP 서버를 TypeScript로 구축하는 방법을 배웠습니다. 서버는 두 가지 도구를 제공합니다. Query DSL을 사용하여 관련 문서를 가져오는 search_docs(와)과, OpenAI 모델을 통해 인용구가 포함된 요약을 생성하고 Claude Desktop을 클라이언트 UI로 사용하는 summarize_and_cite입니다.

다양한 클라이언트와 서버 제공 업체 간의 호환성 미래는 매우 유망해 보입니다. 다음 단계로는 에이전트에 더 많은 기능과 유연성을 추가하는 과정이 포함됩니다. 검색 템플릿을 사용하여 쿼리를 매개변수화함으로써 정확도와 유연성을 얻는 방법에 대한 실용적인 글을 읽어 보실 수 있습니다.

이것이 바로 우리가 읽기 전용 대시보드를 개발한 이유입니다. 여러분이 기다려온 바로 그 제어 기능입니다. 이제 편집 권한이 있는 다른 사용자가 대시보드를 수정하거나 손상시킬 걱정 없이 안심하고 공유하세요.

참고: 읽기 전용 권한은 Elastic Cloud Serverless에서 사용할 수 있으며 Elastic Cloud Hosted 및 Elastic 자체 관리형의 경우 버전 9.3부터 제공됩니다.

“모든 사람이 편집할 수 있을 때 방해가 되는 경우”

그동안 Kibana에서의 공유는 보통 스페이스 수준의 권한을 의미했습니다. 특정 스페이스에서 대시보드를 생성할 수 있는 사용자라면 다른 사용자의 대시보드 역시 편집하거나 삭제할 수 있었습니다. 이는 협업에는 유용하지만 예기치 못한 문제를 일으키기도 합니다. 단 한 번의 편집 실수가 잘못된 의사결정이나 신뢰 상실로 이어지고 막대한 복구 작업이 필요해질 수 있기 때문입니다.

그동안 "대시보드 이름에 '읽기 전용'이라고 적어두고 사용자들이 제발 알아봐 주기만을 바란다"는 식의 임시방편들을 많이 봐왔습니다. 혹은 "태그를 달아두고 아무 일 없기를 간절히 기도한다"는 분들도 계셨죠. 하지만 이러한 막연한 기대는 제대로 된 권한 관리 모델이 아닙니다. 여러분에게는 스페이스 접근 권한을 완전히 막지 않고도 대시보드만 확실하게 잠글 수 있는 실질적인 방법이 필요했습니다.

실제로 어떤 문제가 발생할까요?

데브와 케빈은 모두 운영 스페이스 내 로그 모니터링 대시보드에 대한 편집 권한을 가지고 있습니다. 케빈이 차트를 일부 변경합니다. 나중에 데브가 확인했을 때 대시보드의 숫자는 그녀가 제시했던 수치와 일치하지 않습니다. 결국 무엇이 변경되었는지(종종 기억에 의존하여) 일일이 추적하여 수정해야 하며 잘못된 데이터가 포함된 보고가 얼마나 많이 배포되었는지 우려하게 됩니다.

읽기 전용 대시보드: 합리적인 소유권과 제어

읽기 전용 대시보드는 다른 사용자의 편집 허용 여부를 직접 결정할 수 있는 제어 기능을 제공하여 이 문제를 해결합니다. 대시보드를 공유할 때 편집(기본 설정, 기존과 동일) 또는 보기 중 하나를 선택할 수 있습니다. 보기 모드에서는 작성자 본인과 Kibana 관리자만 대시보드를 수정하거나 삭제할 수 있습니다. 그 외 모든 사용자는 대시보드를 열어보고 활용하며 데이터를 신뢰할 수 있지만 임의로 수정할 수는 없습니다.

주요 혜택

• 대시보드 무결성: 보기 모드에서는 해당 스페이스의 편집 권한이 있는 다른 사용자라도 대시보드를 수정하거나 삭제할 수 없습니다. 만약 시도할 경우에는 대시보드가 잠겨 있다는 안내가 표시됩니다. 여러분의 차트와 로직은 그대로 유지됩니다.
• 주도권 유지: 여러분이 소유자입니다. 소유자는 언제든지 편집하고 세부 조정하거나 업데이트할 수 있습니다. 보기 전용으로 공유한다고 해서 소유자의 권한까지 제한되는 것은 아닙니다. 다만, 다른 사용자가 보게 되는 버전만 고정할 뿐입니다.
• 유연한 라이프사이클: 언제든지 대시보드를 "편집 가능" 상태로 전환할 수 있습니다. 또한 Kibana 관리자는(예: 소유자가 퇴사하는 경우) 모든 대시보드를 지속적으로 관리할 수 있습니다. 관리의 공백이 발생하지 않습니다.

이제 최종 확정된 핵심 업무용 대시보드를 안심하고 광범위하게 공유하며 데이터의 일관성을 유지할 수 있습니다. 이 기능은 Serverless를 포함한 모든 Elastic 티어 및 서비스 모델에서 사용할 수 있습니다.

권한별 기능 안내

역할별 권한 요약:

• 대시보드 소유자: 직접 생성한 대시보드이므로 소유자가 모든 편집 권한을 가집니다.
• Kibana 관리자: 모든 대시보드를 관리할 수 있습니다.
• 스페이스 편집 권한이 있는 사용자: 자신의 대시보드를 생성하고 편집할 수 있습니다. 보기 전용 대시보드는 편집하거나 삭제할 수 없습니다.
• 스페이스 보기 권한 사용자: 대시보드 목록 확인 및 조회만 가능합니다.

읽기 전용 모드 활성화 방법

새 대시보드를 저장할 때 또는 나중에 공유 메뉴에서 보기 전용으로 설정할 수 있습니다.

새 대시보드를 저장하는 경우

• 대시보드를 구성한 후 저장 버튼을 클릭합니다.
• "새 대시보드로 저장" 모달에서 권한을 찾습니다.
• 편집 가능 에서 보기 가능으로 변경합니다.
• 저장을 클릭하면 끝입니다. 이제 다른 모든 사용자에게는 읽기 전용으로 표시됩니다.

이미 소유하고 있는 대시보드의 경우

• 대시보드를 엽니다.
• 대시보드 공유 메뉴를 엽니다.

• 공유 모달에서 권한을 찾아 보기 가능으로 전환합니다. 변경 사항은 즉시 적용되며, 해당 스페이스의 다른 사용자는 더 이상 대시보드를 수정하거나 삭제할 수 없습니다.

• 공유 작업 위에 마우스를 올리면 해당 대시보드에 설정된 권한 유형을 바로 확인할 수 있습니다.

잠겨 있는 대시보드 식별

메인 대시보드 목록에서 편집이나 삭제가 불가능한 대시보드는 선택 체크박스가 비활성화되어 있습니다. 이를 통해 어떤 항목이 보기 전용인지 한눈에 쉽게 확인할 수 있습니다.

대시보드에서 편집 작업이 비활성화되며 해당 대시보드가 보기 전용으로 설정되었음을 안내하는 툴팁이 표시됩니다.

직접 사용해 보기

지금 바로 읽기 전용 대시보드를 이용해 보세요. 대시보드를 생성하고 보기 가능으로 설정한 뒤 공유하기만 하면 됩니다. 팀은 신뢰할 수 있는 단일 소스를 공유하게 되고 여러분은 안심할 수 있습니다. 이제 대시보드 제목에 "편집 금지"라고 적지 않아도 됩니다.

읽기 전용 대시보드를 어떻게 활용하고 계신지 여러분의 이야기가 궁금합니다. 커뮤니티 포럼에서 피드백을 공유하세요.

이 글에서는 에이전트가 자체 컨텍스트를 구축하는 데 필요한 적절한 검색 인터페이스는 무엇인가?라는 질문에 다시 초점을 맞춥니다. 먼저 셸 도구와 전용 데이터베이스 도구 간의 절충점을 다룹니다. 이를 통해 에이전트의 요구에 맞는 인터페이스를 찾는 데 유용한 실용적인 프레임워크를 제공합니다.

'컨텍스트 구축'이란 에이전트에게 실제로 무슨 의미일까요?

초기 검색 증강 생성(RAG) 파이프라인에서는 개발자가 고정된 검색 파이프라인을 설계했고, 대규모 언어 모델(LLM)은 컨텍스트의 수동적인 수신자였습니다. 이는 근본적인 한계였습니다. 필요한지 여부에 관계없이 모든 쿼리에서 컨텍스트가 검색되었지만 실제로 도움이 되는지 확인하지 못했습니다.

에이전트 기반 RAG로의 전환으로 이제 에이전트는 자체 컨텍스트를 구축하기 위한 일련의 검색 도구에 접근할 수 있게 되었습니다. 예를 들어, Claude Code[1]와 Cursor[2] 모두 에이전트가 다양한 검색 도구 간에 선택할 수 있도록 하고, 작업에 실제로 필요한 내용에 따라 이를 연결된 쿼리로 조합할 수도 있습니다.

컨텍스트 엔지니어링을 위한 검색 인터페이스에는 어떤 것이 있나요?

컨텍스트는 웹, 로컬 파일 시스템 또는 데이터베이스와 같은 다양한 위치에 존재할 수 있습니다. 에이전트는 다양한 도구를 통해 이러한 맥락에서 벗어난 데이터 소스 각각과 상호 작용할 수 있습니다.

• 셸 도구는셸 명령을 실행하고 로컬 파일 시스템에 접근할 수 있습니다. 기본 제공 셸 도구의 예로는 Claude API의 bash 도구, OpenClaw의 exec 도구, 그리고 LangChain의 shell 도구입니다.
• 전용 데이터베이스 도구는 MCP(모델 컨텍스트 프로토콜) 서버의 도구(예: Elastic Agent Builder MCP 서버) 또는 사용자 정의 도구(예: run_esql(query) 또는 db_list_index())로, 데이터베이스를 쿼리할 수 있습니다.
• 전용 파일 검색 도구는 (완전한 셸 액세스 권한 없이도) 로컬 파일(또는 업로드된 파일)을 검색하고 읽을 수 있습니다. 기본 제공 파일 검색 도구의 예로는 Gemini API의 파일 검색 도구 또는 OpenAI의 파일 검색 도구가 있습니다.
• 웹 검색 도구는 웹에서 정보를 검색할 수 있습니다.
• 메모리 도구는 (저장 방식에 관계없이) 장기 기억을 저장하고 불러올 수 있습니다.

보시다시피, 셸 도구는 다재다능하며 다음과 같은 다양한 데이터 소스에서 컨텍스트를 검색하는 데 사용할 수 있습니다.

• 파일 시스템: 에이전트는 디렉터리 구조를 탐색하고(ls, find), 관련 콘텐츠를 검색하고(grep, cat), 충분한 컨텍스트를 구축할 때까지 이 과정을 반복합니다.
• 데이터베이스: 에이전트는 데이터베이스 명령줄 인터페이스 (CLI) 도구(예: elasticsearch-sql-cli)를 사용하거나, curl을 통해 HTTP API를 호출하거나, 스크립트를 실행할 수 있습니다. 이는 올바른 도구 사용을 안내하기 위해 에이전트 컨텍스트에 삽입된 재사용 가능하고 문서화된 예시인 에이전트 스킬과 함께 사용하면 특히 유용합니다(예: Elastic Agent Skills for Elasticsearch).
• 웹: 에이전트는 검색 제공업체의 API를 통해 curl 명령을 사용하여 웹 검색을 실행할 수 있습니다.

그러나 셸 도구는 직접적인 시스템 액세스를 제공하므로 격리된 샌드박스 환경에서 실행하고 모든 실행된 명령을 로깅하는 등의 안전 조치가 필요합니다.

각 검색 인터페이스의 사용 시점

적합한 검색 인터페이스는 데이터, 쿼리 패턴 및 사용 사례에 따라 달라집니다. 이 섹션은 실용적인 출발점이 됩니다.

파일 시스템이 데이터베이스를 쓸모없게 만들지는 않습니다

파일 시스템과 데이터베이스의 논쟁은 저장 공간 계층에 관한 것이 아닙니다. 예를 들어, LangChain은 자체 메모리 시스템이 실제로 실제 파일 시스템에 메모리를 저장하지 않는다고 설명합니다. 대신 데이터베이스에 메모리를 저장하고 이를 에이전트에게 파일 세트로 표현합니다[3].

파일 시스템은 코딩 에이전트와 같은 파일 기반 사용 사례에 매우 적합합니다. 또한 임시 메모장이나 작업 메모리로 사용하기에 적합하며 동시성이 문제가 되지 않는 단일 사용자 또는 단일 에이전트 시나리오에 적합합니다. 이러한 경우 물리적 파일 시스템 또는 데이터를 파일 시스템으로 표현하는 것은 목적에 맞춰진 인터페이스에 약속하기 전에 유연성을 제공합니다.

그러나 파일 시스템 저장 공간에는 실제적인 단점이 있습니다. 예를 들어 약한 동시성, 수동 스키마 적용, 원자적 트랜잭션 등이 있습니다. 이러한 단점은 애플리케이션을 확장해야 하거나 다중 에이전트 시나리오로 전환해야 할 때 더욱 분명해집니다. 이러한 단점을 무시하는 사람은 프로덕션 데이터베이스가 이미 제공하는 트랜잭션 안전이나 액세스 제어를 뒷받침하는 수십 년의 엔지니어링 없이 더 나쁜 데이터베이스를 고통스럽게 재창조해야 할 운명에 처하게 됩니다. 또한 대부분의 기업 환경에서는 이미 비즈니스에 중요한 데이터가 저장되어 있는 데이터베이스가 존재하기 때문에 데이터베이스 사용 여부를 선택할 필요가 없습니다.

셸 도구 + 파일 시스템

셸 도구는 파일 시스템 검색의 자연스러운 출발점입니다. 현재 코딩 에이전트가 해당 분야의 발전을 주도하고 있습니다. 로컬 파일의 코드를 다루기 때문에 본질적으로 파일 중심의 사용 사례입니다. 따라서 LLM은 코딩 작업을 위해 훈련 후 단계에서 미세 조정됩니다. 그렇기 때문에 많은 LLM은 코드를 작성하는 것뿐만 아니라 셸 명령을 사용하고 파일 시스템을 탐색하는 데도 능숙합니다.

ls 및 grep과 같이 기본 제공 CLI가 있는 셸 도구를 사용하면 파일을 효과적으로 찾을 수 있습니다. grep에서는 " matplotlib를 가져오는 모든 파일을 찾으세요" 같은 쿼리가 빠르고 정확하며 저렴합니다. 하지만 에이전트가 "우리 앱은 인증 실패를 어떻게 처리하나요?"와 같은 개념적인 쿼리를 처리해야 하는 경우 grep을 사용한 패턴 매칭은 금방 한계에 부딪힐 수 있습니다. 명령줄에 의미 검색 기능을 제공하는 몇 가지 대안이 이러한 격차를 메우기 위해 등장했으며, 여기에는 jina-grep이 포함됩니다.

그러나 grep과 많은 시맨틱 검색 대안들은 코퍼스 전체에서 O(n) 시간 복잡도로 실행됩니다. 코드베이스를 대상으로 하는 사용 사례에서는 이 방식이 괜찮을 수 있습니다. 그러나 데이터가 증가하면 지연이 눈에 띄게 나타납니다. 이 경우 성능을 유지하기 위해 인덱싱된 데이터 저장소가 필요합니다.

셸 도구 + 데이터베이스

데이터에 시맨틱 검색이나 하이브리드 검색과 같은 더 많은 검색 기능을 추가하는 또 다른 방법은 Cursor의 예처럼 데이터를 데이터베이스에 저장하는 것입니다. 또한 데이터에 복잡한 관계형 조인이나 집계가 필요한 경우 데이터베이스 인터페이스는 필수적입니다.

데이터가 파일 시스템이 아닌 데이터베이스에 있을 때, 셸 도구는 특정 사용 사례에서 경량 데이터베이스 인터페이스 역할을 할 수 있습니다. 쿼리가 CLI나 curl 호출로 간단하다면, 전용 데이터베이스 도구는 불필요한 복잡성을 더할 수 있습니다.

이러한 접근 방식은 초기 탐색 단계에서도 적합합니다. 아직 어떤 쿼리 패턴이 개발될지 모를 때 유용합니다. 이 경우, 에이전트 스킬은 목적에 맞춰 제작된 도구에 의존하지 않고도 에이전트에게 올바르게 쿼리할 수 있는 충분한 구조를 제공할 수 있습니다. 하지만 에이전트가 반복적인 작업을 위해 데이터베이스를 쿼리하는 올바른 방법을 파악하는 데 여러 번의 반복이 필요한 경우, 셸 도구를 인터페이스로 사용하는 데 따른 토큰 오버헤드가 추가 도구를 사용하지 않음으로써 얻는 단순성이라는 이점을 더 이상 정당화하지 못합니다.

전용 데이터베이스 도구

특히 반복되는 쿼리 패턴이 구조화되거나 분석적일 때 전용 데이터베이스 도구가 필요해집니다. Vercel과 Braintrust의 블로그 게시물은 고객 지원 티켓 및 영업 통화 기록과 같은 반정형 데이터에 대한 실제 검색 작업에서 서로 다른 검색 도구 세트를 갖춘 에이전트를 비교했습니다(예: "미해결 이슈 중 '보안'을 언급한 것은 몇 개인가요?" 또는 "누군가 버그를 보고하고 나중에 누군가 이를 수정한다고 주장하는 PR을 제출한 이슈를 찾으세요?") [4].

전용 데이터베이스 도구를 사용한 에이전트는 토큰을 더 적게 사용하고, 더 빠르며, 셸 도구와 파일 시스템만 사용한 에이전트보다 실수를 더 적게 했습니다. 이를 통해 알 수 있는 교훈은 쿼리가 반정형 데이터에 대한 분석적 추론을 필요로 할 때 직접적인 데이터베이스 도구가 올바른 선택이라는 것입니다.

검색 인터페이스 결합하기

모든 쿼리를 완벽하게 처리할 수 있는 단일 검색 인터페이스는 없습니다. 예를 들어, Cursor는 셸 도구(grep을 통한 검색용)와 시맨틱 검색 도구를 결합하여 에이전트가 사용자 프롬프트에 따라 적합한 도구를 선택할 수 있도록 합니다. 그들은 에이전트가 특정 기호나 스트링을 매칭하기 위해 grep을 선택하고, 개념적 또는 행동 질문에 대해서는 시맨틱 검색을 선택하며, 탐색적 작업에는 둘 다를 사용한다고 보고합니다.

Vercel 실험 보고서는 동일한 결과를 보여줍니다. 셸 도구와 전용 데이터베이스 도구 모두에 접근할 수 있는 하이브리드 에이전트가 먼저 전용 데이터베이스 도구를 사용한 다음 파일 시스템을 grep하여 결과를 확인함으로써 테스트된 모든 에이전트 중 최고의 성능을 달성했습니다. 하지만 이 접근 방식은 도구 선택과 검증을 위한 추론에 더 많은 토큰과 시간을 사용합니다.

두 예시의 패턴은 동일합니다. 컴포지션이 단일 인터페이스를 능가하지만 컴포지션에는 추가 비용과 지연 시간이 발생한다는 단점이 있습니다.

적합한 도구 세트를 찾기 위한 실용적인 권장 사항

적합한 검색 인터페이스는 간결하고 목적에 부합하며 에이전트의 실제 쿼리 패턴에 맞춰 특화되어 있어야 합니다. 현재 가장 좋은 방법은 수백 개의 MCP 도구를 사용하는 에이전트 대신 가능한 한 적은 수의 도구를 사용하는 에이전트를 보유하는 것입니다. 이는 가능한 모든 도구를 미리 노출할 경우 발생하는 단점이 컨텍스트 윈도우를 비대화시키고 에이전트가 실제로 사용할 도구에 대해 혼란스럽게 만든다는 것입니다. 예를 들어, Claude Code는 보고된 바에 따르면 약 20개의 도구만 가지고 있습니다.

대신, 점진적 공개의 개념은 최소한의 도구 세트로 시작하고 에이전트가 필요할 때만 추가 기능을 발견하도록 하는 것입니다. Anthropic[5] 및 Cursor[6]의 연구에 따르면 이 접근 방식은 47%–85% 사이의 토큰 절감 효과를 가져옵니다. 예를 들어, Claude Code는 이를 직접 구현하여 에이전트가 API나 데이터베이스를 쿼리하는 방법을 점진적으로 발견할 수 있도록 하며, 이러한 지식이 모든 LLM 호출에서 컨텍스트를 소비하지 않도록 합니다.

에이전트의 쿼리 패턴에 익숙해지면, 에이전트가 기본적으로 액세스할 수 있는 검색 도구 세트를 다시 검토할 수 있습니다. 이 절충점을 고려할 때 유용한 방법은 '낮은 바닥, 높은 천장' 원칙에 다라 어떤 도구를 선택할지 결정하는 것입니다. '높은 천장' 도구는 에이전트의 잠재력을 제한하지 않습니다. 예를 들어, 다목적 셸 도구를 사용하면 에이전트가 애매한 쿼리를 포함한 전체 데이터베이스 쿼리를 작성할 수 있지만, 추론 오버헤드, 더 높은 지연 시간, 더 낮은 신뢰성이라는 대가가 따릅니다.

'낮은 바닥' 도구는 그 반대입니다. 이들은 특정 쿼리를 처리하는 전문화된 도구로, 에이전트가 최소한의 추론 오버헤드로 즉시 접근할 수 있어 비용을 낮추고 신뢰성을 높입니다. 그러나 초기 엔지니어링이 필요하고, 모든 가능한 쿼리를 다룰 수 없으며, 에이전트가 올바른 도구를 선택하기 더 어렵게 만들 수 있습니다.

각 도구를 스펙트럼으로 생각해 보세요. '낮은 바닥' 도구는 에이전트가 올바르게 사용하기 쉽지만 범위가 좁습니다. '높은 천장' 도구는 다용도이지만 효과적으로 사용하기 위해서는 더 많은 추론이 필요합니다.

대부분의 에이전트는 다양한 검색 도구의 조합이 필요합니다. 하지만 각 도구마다 추가 기능이 필요합니다. 다목적 검색 도구(예: search_database() 도구 또는 셸 도구)로 시작하는 것이 좋습니다. 그런 다음 보안 목적으로 이미 보관하고 있는 명령 로그를 재사용하여 도구 호출, 재시도 및 사용자 쿼리당 호출 횟수를 포함하여 에이전트가 실제로 수행하는 작업을 추적하세요. 그리고 쿼리 패턴이 반복되거나 실패하는 것을 발견하면 이를 위한 전용 도구를 구축해야 한다는 신호입니다.

요약

파일시스템 대 데이터베이스 논쟁은 엔지니어들이 묻고 있는 에이전트가 자체 컨텍스트를 구축하는 데 필요한 적절한 검색 인터페이스는 무엇인가?라는 실제 질문에서 주의를 분산시키고 있습니다. 정답은 '하나도 없다'일 가능성이 높습니다.

셸 도구는 다양한 외부 소스와 상호 작용할 수 있는 다용도 도구이므로 좋은 출발점이 될 수 있습니다. 하지만 구조화된 분석 쿼리가 필요한 사용 사례에서는 전용 데이터베이스 도구보다 효율성과 정확성이 떨어집니다.

목표는 에이전트의 실제 쿼리 패턴을 효과적으로 처리할 수 있는 최소한의 검색 도구 세트를 찾는 것입니다. 셸 도구를 사용하여 에이전트가 실제로 수행하는 작업을 기록하세요. 쿼리 패턴이 반복적으로 실패하는 경우, 전문화된 도구를 개발할 시점입니다.

참고 자료

1. Thariq(Anthropic). Claude Code 구축에서 얻은 교훈: 에이전트처럼 보기(2026).

2. Cursor: 문서. 시맨틱 및 에이전트 검색(2026).

3. Harrison Chase(LangChain). Agent Builder의 메모리 시스템 구축 방법(2026).

4. Ankur Goyal(Braintrust) 및 Andrew Qu(Vercel). "bash만으로 충분한지" 테스트하기(2026).

5. Anthropic. Claude 개발자 플랫폼의 고급 도구 활용 소개(2025).

6. Cursor. 동적 컨텍스트 검색(2026년).

파티가 점점 붐비고 있습니다

여러분이 피자 파티를 주최하는 중입니다. 몇 명의 친구들이 파티 장소의 각기 다른 장소에서 서빙을 돕고 있습니다. 각 친구에게 피자를 한 조각씩 건네주면, 친구들은 도착하는 배고픈 손님들에게 피자 조각을 나눠주기 시작합니다.

처음에는 모든 것이 순조롭게 진행됩니다. 손님 몇 명이 조금씩 들어오고, 친구들이 피자 조각을 나눠 주니, 모두가 만족합니다. 하지만 곧 사워도우 피자에 대한 소문이 퍼지기 시작합니다. 초인종이 계속 울립니다. 손님들이 몰려듭니다. 곧 모두가 먹고 싶어 하는 페퍼로니 피자를 들고 있는 친구 주위로 사람들이 모여들기 시작합니다.

페퍼로니 피자를 든 친구는 어쩔 줄을 모릅니다. 손님들이 기다리고 있으며, 점점 불만이 쌓이고 있고, 긴 대기 줄이 형성되었습니다. 한편, 마르게리타 피자를 든 친구는 한 조각 달라고 하는 사람이 거의 없이 가만히 서 있습니다.

이제 어떻게 할까요?

여러분은 페퍼로니 피자 몇 개를 더 주문하여 다른 친구들에게 건넵니다. 이제 한 명이 아닌 세 명의 친구가 페퍼로니 피자를 들고 있습니다. 인파가 분산되어 갑자기 3배나 많은 손님을 한꺼번에 대접할 수 있습니다.

파티를 더 주최할수록 몇 가지 사실이 분명해집니다.

• 모든 피자가 똑같이 인기 있는 것은 아닙니다. 어떤 것은 수요가 많고, 다른 것은 수요가 적습니다. 인기 없는 피자는 추가 '사본'이 없어도 됩니다. 대기열이 있는 것만 추가하면 됩니다.
• 대기열이 너무 길어지기 전에 피자를 더 주문하세요. 친구가 허둥지둥거리고 손님들이 화를 내며 떠나기 시작할 때까지 기다린다면, 너무 오래 기다린 것입니다. 인파가 몰리는 게 보이면 피자를 한 판 더 주문하는 것이 좋습니다.
• 피자를 너무 빨리 버리지 마세요. 페퍼로니 피자 주변에 5분 동안 인파가 줄었다고 해서 혼잡한 시간이 끝난 것은 아닙니다. 어쩌면 사람들은 음료를 다시 채우고 있거나 서로 대화하고 있을지도 모릅니다(요즘도 그러나요?). 추가 피자를 유지해 주세요. 잠잠한 상태가 한동안 계속된다면, 그땐 피자를 치워도 됩니다.
• 도와주는 친구 수만큼만 피자를 나눠줄 수 있습니다. 도와주는 친구가 네 명이면 피자를 열 판으로 늘려도 결과는 달라지지 않습니다. 한 번에 네 조각만 제공할 수 있습니다. 피자의 수를 도와주는 인원에 맞춰야 합니다.
• 친구가 떠나면 피자를 가져오세요. 친구 중 한 명이 떠나야 한다면 즉시 그들의 피자를 가져오세요. 피자를 방치하면 안 됩니다. 다른 사람에게 건네주거나 치워두세요.

피자부터 복제품까지

이것을 다시 Elasticsearch에 매핑해 볼까요.

이 비유에서 피자는 복제본(인덱스 샤드 복사본), 서빙을 돕는 친구들은 검색 노드, 배고픈 손님은 검색 쿼리, 주변에 인파가 모인 인기 있는 피자는 검색 부하가 높은 핫 인덱스입니다.

특정 인덱스에서 검색 트래픽이 증가하면 추가 복제본을 생성하여 검색 노드 전체에 배포합니다. 모든 복제본은 해당 인덱스에 어떤 쿼리든 서빙할 수 있습니다. 마치 페퍼로니 피자를 든 친구가 페퍼로니 피자 조각을 나눠줄 수 있는 것처럼 말이죠. 복제본 수가 많을수록 처리량이 높아집니다. 복제본이 세 개면 복제본 한 개보다 초당 3배 더 많은 쿼리를 처리할 수 있습니다.

허기 측정

피자를 몇 개나 주문할지 결정하기 전에, 우리는 사람들이 얼마나 배고픈지 알아야 합니다.

Elasticsearch는 모든 샤드의 검색 부하를 추적합니다. 검색 부하는 샤드가 처리하는 검색 활동의 양을 나타내는 지표입니다. 전체 검색 수요를 파악하기 위해 인덱스의 전체 샤드에서 이를 집계합니다.

가장 중요한 것은 상대적 검색 부하입니다. 즉, 프로젝트의 전체 검색 트래픽 중 각 인덱스에 도달하는 비율을 파악하는 것입니다. 한 인덱스가 전체 검색의 60%를 받고 다른 인덱스가 5%를 받는다면, 어디에 용량을 추가해야 할지 알 수 있겠죠.

피자에 숨겨진 수학적 원리

다음 공식에 따라 최적의 복제본 수를 계산합니다.

desired_replicas = min(ceil(L × N / (S × X)), N)

위치:

• L은 인덱스의 상대적 검색 부하(0~1 사이)입니다.
• N =프로젝트에서 원하는 검색 노드 개수입니다.
• S = 인덱스의 샤드 수입니다.
• X = 핫스팟을 방지하기 위한 임계값입니다(기본값: 0.5).

예시: 검색 노드 4개, 기본 샤드 2개를 가진 인덱스 1개, 검색 트래픽의 80%를 수신하는 경우:

desired_replicas = min(ceil(0.8 × 4 / (2 × 0.5)), 4)
                 = min(4, 4)
                 = 4

이 핫 인덱스는 검색 노드에 분산된 네 개의 복제본을 갖습니다.

임계값 X(기본값은 0.5)가 중요합니다. 복제본이 완전히 과부하될 때까지 기다리지 않고, 용량의 절반에 도달하면 규모를 확장합니다. 손님이 떠날 때가 아니라 인파가 모이기 시작할 때 여분의 피자를 나눠줍니다.

신속한 확장과 느긋한 축소

검색 부하가 증가하면 즉시 복제본을 추가합니다. 사용자를 기다리게 할 이유가 없습니다.

검색 부하가 떨어지면 조치를 취하기 전에 잠시 기다립니다. 낮은 수요가 약 30분 동안 일관적으로 지속되어야 복제본을 줄입니다. (이는 급증하는 트래픽을 처리하기 위한 것이며 조용한 순간이 파티가 끝났다는 의미는 아닙니다.)

복제본을 추가하려면 비용이 들기 때문에 이는 중요한 문제입니다. 새로운 복제본은 데이터를 복사하고 캐시를 워밍한 후 쿼리를 효율적으로 처리합니다. 너무 성급하게 복제본을 제거하면 트래픽의 자연스러운 변동에 따라 지속적으로 이러한 시작 비용을 지불하게 됩니다.

토폴로지 경계 준수

복제본 수는 검색 노드 수를 초과할 수 없습니다. 노드보다 더 많은 복제본을 갖는 것은 아무런 이점이 없습니다(피자 조각을 제공하는 친구의 수만큼만 피자를 제공할 수 있습니다).

프로젝트에서 노드가 제거되면 복제본 수를 즉시 줄여서 노드 수와 일치시킵니다. 할당되지 않은 복제본을 보유할 수 없기 때문에 쿨다운을 기다리지 않습니다. 친구가 떠나는 순간, 그 피자도 제거됩니다.

더 큰 서버리스 그림

검색 로드 밸런싱을 위한 복제본은 다른 자동 확장 시스템과 함께 작동합니다.

• 검색 자동 확장은 검색 노드 수(도와주는 친구 수)를 조정합니다.
• 검색 부하 분산을 위한 복제본은 인덱스당 복제본 수(종류별로 필요한 피자 수)를 조정하여 트래픽을 분산합니다.
• 데이터 스트림 자동 샤딩은 쓰기에 대한 샤드 수를 최적화합니다(각 피자를 자르는 방법은 이전 포스트에서 다뤘습니다).

중요한 설계 원칙: 로드 밸런싱용 복제본은 검색 자동 확장을 직접 유발하지 않습니다. 대신, 검색 요청을 더 많은 복제본에 분산함으로써 검색 노드 전체의 리소스 사용량을 높일 수 있습니다. 이렇게 높은 사용량은 필요한 경우 용량을 추가하도록 기존의 자동 확장 로직을 작동시킵니다. 로드 밸런싱을 위한 복제본은 자동 확장이 제 기능을 수행하도록 하여, 다른 노드가 사용되지 않는 동안 모든 트래픽이 단일 복제본에 병목 현상을 일으키는 대신 검색 노드가 실제로 사용되도록 합니다.

이것이 귀하에게 의미하는 것

어떤 인덱스가 인기를 끌지 예측할 필요는 없습니다. 트래픽 패턴이 변경될 때 복제본을 수동으로 조정하지 않아도 됩니다. 가장 사용량이 많은 인덱스에 과부하가 걸렸다고 해서 새벽 3시에 일어날 필요는 없습니다.

시스템은 대기열이 형성되는 위치를 감지하여 해당 지점에 더 많은 피자를 주문합니다. 콜드 인덱스는 불필요한 복제본에 자원을 낭비하지 않습니다. 핫 인덱스는 필요한 용량을 확보합니다. 예산은 중요한 곳에 사용됩니다.

결론

자동 샤딩 게시물에서 피자를 적절하게 잘랐습니다. 이제 검색 부하 분산을 위한 복제본으로 배고픈 사람들이 몰려들 때 충분한 양의 피자를 적절한 사람들에게 전달하겠습니다.

Elastic Cloud Serverless를 사용하면 피자 배달을 처리해 드립니다.

필수 구성 요소

• Elasticsearch 9.3 또는 Elastic Cloud Serverless: 이 지침을 따라 클라우드 배포를 생성하거나, start-local 퀵스타트를 사용할 수 있습니다.
• Python 3.12: Python을 여기에서 다운로드하세요.
• Hugging Face 액세스 토큰.

Hugging Face 추론 엔드포인트를 사용하여 채팅 완료 수행하기

먼저, Elasticsearch를 Hugging Face 엔드포인트에 연결하여 블로그 게시물 모음에서 AI 기반 추천을 생성하는 실용적인 예제를 구축할 것입니다. 앱 지식 기반 시스템을 위해, 회사 블로그 기사의 데이터 세트를 사용할 것입니다. 이 데이터 세트에는 귀중하지만 종종 탐색하기 어려운 정보가 포함되어 있습니다.

이 엔드포인트를 사용하면 시맨틱 검색을 통해 주어진 쿼리에 가장 적합한 문서를 검색할 수 있으며, Hugging Face LLM이 해당 결과를 바탕으로 문맥에 맞는 짧은 추천 결과를 생성합니다.

구축할 정보 흐름에 대한 개괄적인 내용을 살펴보겠습니다.

이 기사에서는 SmolLM3-3B의 컴팩트한 크기와 강력한 다국어 추론 및 도구 호출 기능을 결합하는 능력을 테스트할 것입니다. 검색 쿼리를 기반으로 일치하는 모든 콘텐츠(영어 및 스페인어)를 LLM으로 전송하고, 검색 쿼리와 결과를 바탕으로 맞춤형 설명이 포함된 추천 기사 목록을 생성합니다.

AI 추천 생성 시스템이 포함된 기사 사이트의 UI는 다음과 같을 수 있습니다.

이 애플리케이션의 전체 구현은 연결된 노트북에서 확인하실 수 있습니다.

Elasticsearch 추론 엔드포인트 구성하기

Elasticsearch Hugging Face 추론 엔드포인트를 사용하려면 Hugging Face API 키와 실행 중인 Hugging Face 엔드포인트 URL라는 두 가지 중요한 요소가 필요합니다. 다음과 같이 보여야 합니다.

PUT _inference/chat_completions/hugging-face-smollm3-3b
{
    "service": "hugging_face",
    "service_settings": {
        "api_key": "hugging-face-access-token", 
        "url": "url-endpoint" 
    }
}

Elasticsearch의 Hugging Face 추론 엔드포인트는 text_embedding, completion, chat_completion, rerank 등 다양한 작업 유형을 지원합니다. 이 블로그 글에서는 검색 결과와 시스템 프롬프트를 바탕으로 대화형 추천을 생성하는 모델이 필요하기 때문에 chat_completion를 사용합니다. 이 엔드포인트를 통해 Elasticsearch API를 사용하여 Elasticsearch에서 직접 채팅 완료를 간단하게 수행할 수 있습니다.

POST _inference/chat_completion/hugging-face-smollm3-3b/_stream
{
  "messages": [
      { "role": "user", "content": "" }
  ]
}

이것은 애플리케이션의 핵심 역할을 하며, 프롬프트와 모델을 통과할 검색 결과를 받습니다. 이론을 다뤘으니 이제 애플리케이션 구현을 시작해 보겠습니다.

Hugging Face에서 추론 엔드포인트 설정하기

Hugging Face 모델을 배포하기 위해 Hugging Face 원클릭 배포를 사용할 것입니다. 이는 모델 엔드포인트를 배포하기 위한 쉽고 빠른 서비스입니다. 이 서비스는 유료 서비스이므로 이용 시 추가 비용이 발생할 수 있습니다. 이 단계에서는 기사 추천을 생성하는 데 사용될 모델 인스턴스를 생성합니다.

원클릭 카탈로그에서 모델을 선택할 수 있습니다.

SmolLM3-3B 모델을 선택합니다.

여기에서 Hugging Face 엔드포인트 URL을 가져옵니다.

Elasticsearch Hugging Face 추론 엔드포인트 설명서에서 언급했듯이, 텍스트 생성에는 OpenAI API와 호환되는 모델이 필요합니다. 그러므로 Hugging Face 엔드포인트 URL에 /v1/chat/completions 하위 경로를 추가해야 합니다. 최종 결과는 다음과 같습니다.

https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions

이렇게 준비되면 Python 노트북에서 코딩을 시작할 수 있습니다.

Hugging Face API 키 생성하기

Hugging Face 계정을 만들고 다음 안내에 따라 API 토큰을 받습니다. 세분화(특정 리소스에만 액세스를 제공하므로 프로덕션에 권장), 읽기(읽기 전용 액세스), 쓰기(읽기 및 쓰기 액세스용)의 세 가지 토큰 유형 중 선택할 수 있습니다. 이 튜토리얼에서는 추론 엔드포인트만 호출하면 되므로 읽기 토큰으로 충분합니다. 다음 단계를 위해 이 키를 저장해 두세요.

Elasticsearch 추론 엔드포인트 설정

먼저, Elasticsearch Python 클라이언트를 선언해 보겠습니다.

os.environ["ELASTICSEARCH_API_KEY"] = "your-elasticsearch-api-key"
os.environ["ELASTICSEARCH_URL"] = "https://xxxx.us-central1.gcp.cloud.es.io:443"

es_client = Elasticsearch(
    os.environ["ELASTICSEARCH_URL"], api_key=os.environ["ELASTICSEARCH_API_KEY"]
)

다음으로, Hugging Face 모델을 사용하는 Elasticsearch 추론 엔드포인트를 생성해 보겠습니다. 이 엔드포인트를 통해 블로그 게시물과 모델에 전달된 프롬프트를 기반으로 응답을 생성할 수 있습니다.

INFERENCE_ENDPOINT_ID = "smollm3-3b-pnz"

os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"] = (
 "https://j2g31h0futopfkli.us-east-1.aws.endpoints.huggingface.cloud/v1/chat/completions"
)
os.environ["HUGGING_FACE_API_KEY"] = "hf_xxxxx"

resp = es_client.inference.put(
        task_type="chat_completion",
        inference_id=INFERENCE_ENDPOINT_ID,
        body={
            "service": "hugging_face",
            "service_settings": {
                "api_key": os.environ["HUGGING_FACE_API_KEY"],
                "url": os.environ["HUGGING_FACE_INFERENCE_ENDPOINT_URL"],
            },
        },
    )

데이터 세트

데이터 세트에는 전체 워크플로우에서 사용되는 다국어 콘텐츠 세트를 나타내는 쿼리될 블로그 게시물이 포함되어 있습니다.

// Articles dataset document example: 
{
    "id": "6",
    "title": "Complete guide to the new API: Endpoints and examples",
    "author": "Tomas Hernandez",
    "date": "2025-11-06",
    "category": "tutorial",
    "content": "This guide describes in detail all endpoints of the new API v2. It includes code examples in Python, JavaScript, and cURL for each endpoint. We cover authentication, resource creation, queries, updates, and deletion. We also explain error handling, rate limiting, and best practices. Complete documentation is available on our developer portal."
  }

Elasticsearch 매핑

데이터 세트가 정의되었으므로, 이제 블로그 게시물 구조에 적합한 데이터 스키마를 생성해야 합니다. 다음 인덱스 매핑은 Elasticsearch에 데이터를 저장하는 데 사용됩니다.

INDEX_NAME = "blog-posts"

mapping = {
    "mappings": {
        "properties": {
            "id": {"type": "keyword"},
            "title": {
                "type": "object",
                "properties": {
                    "original": {
                        "type": "text",
                        "copy_to": "semantic_field",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                    "translated_title": {
                        "type": "text",
                        "fields": {"keyword": {"type": "keyword"}},
                    },
                },
            },
            "author": {"type": "keyword", "copy_to": "semantic_field"},
            "category": {"type": "keyword", "copy_to": "semantic_field"},
            "content": {"type": "text", "copy_to": "semantic_field"},
            "date": {"type": "date"},
            "semantic_field": {"type": "semantic_text"},
        }
    }
}


es_client.indices.create(index=INDEX_NAME, body=mapping)

여기에서 데이터가 어떻게 구성되어 있는지 더욱 명확하게 확인할 수 있습니다. 자연어를 기반으로 결과를 검색하는 데 시맨틱 검색을 사용하고, copy_to 속성을 사용하여 필드 내용을 semantic_text 필드로 복사합니다. 또한 title 필드에는 두 개의 하위 필드가 있습니다. original 하위 필드는 기사의 원래 언어에 따라 영어 또는 스페인어로 제목을 저장하며, translated_title 하위 필드는 스페인어 기사에만 존재하고 원래 제목의 영어 번역을 포함합니다.

데이터 수집

다음 코드 스니펫은 벌크 API를 사용하여 블로그 게시물 데이터 세트를 Elasticsearch로 수집합니다.

def build_data(json_file, index_name):
    with open(json_file, "r") as f:
        data = json.load(f)

    for doc in data:
        action = {"_index": index_name, "_source": doc}
        yield action


try:
    success, failed = helpers.bulk(
        es_client,
        build_data("dataset.json", INDEX_NAME),
    )
    print(f"{success} documents indexed successfully")

    if failed:
        print(f"Errors: {failed}")
except Exception as e:
    print(f"Error: {str(e)}")

이제 기사들이 Elasticsearch에 수집되었으니, semantic_text 필드에 대해 검색할 수 있는 함수를 만들어야 합니다.

def perform_semantic_search(query_text, index_name=INDEX_NAME, size=5):
    try:
        query = {
            "query": {
                "match": {
                    "semantic_field": {
                        "query": query_text,
                    }
                }
            },
            "size": size,
        }

        response = es_client.search(index=index_name, body=query)
        hits = response["hits"]["hits"]

        return hits
    except Exception as e:
        print(f"Semantic search error: {str(e)}")
        return []

추론 엔드포인트를 호출하는 함수도 필요합니다. 이 경우 chat_completion 작업 유형을 사용하여 엔드포인트를 호출하여 스트리밍 응답을 받습니다.

def stream_chat_completion(messages: list, inference_id: str = INFERENCE_ENDPOINT_ID):
    url = f"{ELASTICSEARCH_URL}/_inference/chat_completion/{inference_id}/_stream"
    payload = {"messages": messages}
    headers = {
        "Authorization": f"ApiKey {ELASTICSEARCH_API_KEY}",
        "Content-Type": "application/json",
    }

    try:
        response = requests.post(url, json=payload, headers=headers, stream=True)
        response.raise_for_status()

        for line in response.iter_lines(decode_unicode=True):
            if line:
                line = line.strip()

                if line.startswith("event:"):
                    continue

                if line.startswith("data: "):
                    data_content = line[6:]

                    if not data_content.strip() or data_content.strip() == "[DONE]":
                        continue

                    try:
                        chunk_data = json.loads(data_content)

                        if "choices" in chunk_data and len(chunk_data["choices"]) > 0:
                            choice = chunk_data["choices"][0]
                            if "delta" in choice and "content" in choice["delta"]:
                                content = choice["delta"]["content"]
                                if content:
                                    yield content

                    except json.JSONDecodeError as json_err:
                        print(f"\nJSON decode error: {json_err}")
                        print(f"Problematic data: {data_content}")
                        continue

    except requests.exceptions.RequestException as e:
        yield f"Error: {str(e)}"

이제 의미 탐색 함수와 chat_completions 추론 엔드포인트, 추천 엔드포인트를 호출하여 카드에 할당될 데이터를 생성할 수 있습니다.

def recommend_articles(search_query, index_name=INDEX_NAME, max_articles=5):
    print(f"\n{'='*80}")
    print(f"🔍 Search Query: {search_query}")
    print(f"{'='*80}\n")

    articles = perform_semantic_search(search_query, index_name, size=max_articles)

    if not articles:
        print("❌ No relevant articles found.")
        return None, None

    print(f"✅ Found {len(articles)} relevant articles\n")

    # Build context with found articles
    context = "Available blog articles:\n\n"
    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)
        context += f"Article {i}:\n"
        context += f"- Title: {source.get('title', 'N/A')}\n"
        context += f"- Author: {source.get('author', 'N/A')}\n"
        context += f"- Category: {source.get('category', 'N/A')}\n"
        context += f"- Date: {source.get('date', 'N/A')}\n"
        context += f"- Content: {source.get('content', 'N/A')}\n\n"

    system_prompt = """You are an expert content curator that recommends blog articles.

    Write recommendations in a conversational style starting with phrases like:
    - "If you're interested in [topic], this article..."
    - "This post complements your search with..."
    - "For those looking into [topic], this article provides..."


    FORMAT REQUIREMENTS:
    - Return ONLY a JSON array
    - Each element must have EXACTLY these three fields: "article_number", "title", "recommendation"
    - If the original title is in spanish, use the "translated_title" subfield in the "title" field

    Keep each recommendation concise (2-3 sentences max) and focused on VALUE to the reader.

    EXAMPLE OF CORRECT FORMAT:
    [
        {"article_number": 1, "title": "Article title in english", "recommendation": "If you are interested in [topic], this article provides..."},
        {"article_number": 2, "title": "Article title in english", "recommendation": " for those looking into [topic], this article provides..."}
    ]

    Return ONLY the JSON array following this exact structure."""

    user_prompt = f"""Search query: "{search_query}"

    Generate recommendations for the following articles: {context}
    """

    messages = [
        {"role": "system", "content": "/no_think"},
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": user_prompt},
    ]

    # LLM generation
    print(f"{'='*80}")
    print("🤖 Generating personalized recommendations...\n")

    full_response = ""

    for chunk in stream_chat_completion(messages):
        print(chunk, end="", flush=True)
        full_response += chunk

    return context, articles, full_response

마지막으로, 정보를 추출하여 인쇄할 수 있도록 서식을 지정해야 합니다.

def display_recommendation_cards(articles, recommendations_text):
    print("\n" + "=" * 100)
    print("📇 RECOMMENDED ARTICLES".center(100))
    print("=" * 100 + "\n")

    # Parse JSON recommendations - clean tags and extract JSON
    recommendations_list = []
    try:

        # Clean up  tags
        cleaned_text = re.sub(
            r".*?", "", recommendations_text, flags=re.DOTALL
        )
        # Remove markdown code blocks ( ... ``` or ``` ... ```)
        cleaned_text = re.sub(r"```(?:json)?", "", cleaned_text)
        cleaned_text = cleaned_text.strip()

        parsed = json.loads(cleaned_text)

        # Extract recommendations from list format
        for item in parsed:
            article_number = item.get("article_number")
            title = item.get("title", "")
            rec_text = item.get("recommendation", "")

            if article_number and rec_text:
                recommendations_list.append(
                    {
                        "article_number": article_number,
                        "title": title,
                        "recommendation": rec_text,
                    }
                )
    except json.JSONDecodeError as e:
        print(f"⚠️  Could not parse recommendations as JSON: {e}")
        return

    for i, article in enumerate(articles, 1):
        source = article.get("_source", article)

        # Card border
        print("┌" + "─" * 98 + "┐")

        # Find recommendation and title for this article number
        recommendation = None
        title = None
        for rec in recommendations_list:
            if rec.get("article_number") == i:
                recommendation = rec.get("recommendation")
                title = rec.get("title")
                break

        # Print title
        title_lines = textwrap.wrap(f"📌 {title}", width=94)
        for line in title_lines:
            print(f"│  {line}".ljust(99) + "│")

        # Card border
        print("├" + "─" * 98 + "┤")

        # Print recommendation
        if recommendation:
            recommendation_lines = textwrap.wrap(recommendation, width=94)
            for line in recommendation_lines:
                print(f"│  {line}".ljust(99) + "│")

        # Card bottom
        print("└" + "─" * 98 + "┘")

보안 블로그 게시물에 대해 질문하여 이를 테스트해 보겠습니다.

search_query = "Security and vulnerabilities"

context, articles, recommendations = recommend_articles(search_query)

print("\nElasticsearch context:\n", context)

# Display visual cards
display_recommendation_cards(articles, recommendations)

여기서 워크플로우가 생성한 콘솔의 카드를 볼 수 있습니다.

이 파일에서 모든 히트와 LLM 응답을 포함한 전체 결과를 확인하실 수 있습니다.

"보안 및 취약점"과 관련된 기사를 찾고 있습니다. 이 질문은 Elasticsearch에 저장된 문서에 대한 검색 쿼리로 사용됩니다. 검색된 결과는 모델로 전달되어 해당 콘텐츠를 기반으로 추천을 생성합니다. 보시다시피, 이 모델은 독자가 클릭하도록 동기를 부여할 수 있는 매력적인 짧은 텍스트를 훌륭하게 생성했습니다.

결론

이 예시는 Elasticsearch와 Hugging Face를 결합하여 AI 애플리케이션을 위한 빠르고 효율적인 중앙 집중식 시스템을 만드는 방법을 보여줍니다. 이 접근 방식은 수동 작업을 줄이고 Hugging Face의 광범위한 모델 카탈로그 덕분에 유연성을 제공합니다. SmolLM3-3B를 사용하면 특히 소형 다국어 모델이 시맨틱 검색과 결합될 때 여전히 의미 있는 추론과 콘텐츠 생성을 제공할 수 있음을 보여줍니다. 이러한 도구들을 함께 사용하면 지능형 콘텐츠 분석 및 다국어 애플리케이션 구축을 위한 확장성 있는 효과적인 기반을 마련할 수 있습니다.

이를 해결하기 위해 Elasticsearch와 같은 검색 엔진은 두 가지 주요 최적화 전략을 사용합니다.

1. 근사 검색(계층적 탐색 가능 스몰 월드 [HNSW]): 모든 문서를 스캔하는 대신, 답이 있을 가능성이 높은 근처로 빠르게 이동할 수 있는 탐색 그래프를 구축합니다.
2. 양자화: 메모리 사용량을 줄이고 계산 속도를 높이기 위해 벡터를 압축합니다(예: 32비트 부동소수점에서 8비트 정수 또는 1비트 이진 값으로).

하지만 최적화에는 정확성이라는 대가가 따르는 경우가 많습니다.

"만약 데이터를 압축하고 검색 중에 지름길을 택한다면 최상의 결과를 놓치게 될까요?" 혹은 "이러한 최적화가 검색 엔진의 관련성을 저하시킬까요?"라는 두려움이 당연히 생길 수 있습니다.

Elastic의 정량화가 결과를 저하시키지 않는다는 것을 증명하기 위해, DBPedia-14 데이터 세트를 사용해 반복 가능한 테스트 하네스를 구축하여 Elasticsearch에서 기본 최적화를 사용할 때 속도와 얼마나 많은 정확도(특히, 리콜)를 교환하는지 정확히 계산했습니다.

tldr: 생각보다 훨씬 적을 가능성이 높습니다. 여기에서 노트북을 확인하고 직접 사용해 보세요.

정의(비전문가를 위한)

코드를 살펴보기 전에 먼저 몇 가지 용어를 정리해 보겠습니다.

• 정확도 대 리콜: 정확도는 주관적입니다(좋은 것을 찾았는가?). 리콜은 수학적입니다. 데이터베이스에 검색어와 수학적으로 완벽하게 일치하는 문서가 10개 있고 검색 엔진이 그 중 9개를 찾았다면 리콜 확률은 90%(또는 0.9)입니다.
• 정확한 검색(평면 검색): 때때로 "무차별 대입" 방법이라고도 합니다. 검색 엔진은 색인에 있는 모든 문서를 스캔하여 거리를 계산합니다.
  • 장점: 리콜이 100% 완벽합니다.
  • 단점: 계산 비용이 높고 규모가 커질수록 느려집니다.
• 근사 검색(HNSW): "지름길" 방식입니다. 검색 엔진이 HNSW 그래프를 구축합니다. 그래프를 탐색하여 최근접 이웃을 찾습니다.
  • 장점: 매우 빠르고 확장 가능합니다.
  • 단점: 그래프 탐색이 너무 일찍 중단되면 이웃을 놓칠 가능성이 있습니다.

실험: 정확한 값과 근사치 비교

리콜을 테스트하기 위해 텍스트 분류 모델을 학습하고 평가하는 데 일반적으로 사용되는 14개 온톨로지 클래스에 걸친 제목과 초록으로 구성된 대규모 데이터 세트인 DBPedia-14 데이터 세트를 사용했습니다. 특히 "영화" 카테고리에 초점을 맞출 것입니다. 최적화된 프로덕션 설정을 수학적으로 완벽한 기준 데이터와 비교하고 싶었습니다.

이 실험에서는 jina-embeddings-v5-text-small 모델을 사용하고 있습니다. 이 모델은 텍스트 표현에 대한 업계 벤치마크를 선도하는 최첨단 다국어 모델입니다. 이 모델이 고성능 임베딩의 현재 표준을 정의하기 때문에 이 모델을 선택했습니다. Jina v5의 탁월한 정확도와 Elasticsearch의 네이티브 양자화 기능을 결합함으로써, 계산 효율성이 뛰어나면서도 검색 품질을 저하시키지 않는 검색 아키텍처를 구현할 수 있음을 보여줍니다.

이중 매핑으로 색인을 설정했습니다. 동일한 텍스트를 두 개의 서로 다른 필드에 동시에 수집했습니다.

1. content.raw 유형: flat. 이로 인해 Elasticsearch는 전체 Float32 벡터에 대해 무차별 대입 스캔을 수행하게 됩니다. 이렇게 하면 정확한 일치 결과가 반환되며 기준선으로 사용됩니다.
2. content 유형 semantic_text. 기본값으로 HNSW + 더 나은 이진 양자화(BBQ)를 사용합니다. 이것이 근사 일치를 위한 표준적이고 최적화된 생산 설정입니다.

Recall@10 테스트

메트릭으로는 Recall@10을 사용했습니다.

무작위로 영화 50편을 골라 두 필드에 대해 동일한 쿼리를 실행했습니다.

• 정확한 (평면) 검색에서 상위 10개 이웃의 ID가 [1, 2, 3... 10]인 경우.
• 그리고 대략적인 (HNSW) 검색은 ID [1, 2, 3... 9, 99]를 반환합니다.
• 상위 10개 중 9개를 정확히 찾아냈습니다. 점수는 0.9점입니다.

다음은 사용한 매핑입니다.

# The "Control Group": Forces exact brute-force scan
"raw": {
    "type": "semantic_text",
    "inference_id": ".jina-embeddings-v5-text-small",
    "index_options": {
        "dense_vector": {
            "type": "flat"
        }
    }
}

결과: 성공의 "플랫 라인"

전체 데이터 세트를 다시 로드하고 1,000~40,000개의 문서 색인 크기에 대해 테스트하는 확장성 테스트를 실행했습니다.

리콜 점수에 대한 자세한 내용은 다음과 같습니다.

결과는 놀라울 정도로 안정적이었습니다. 규모를 확장했음에도 불구하고, 근사 검색은 무차별 대입 방식의 정확한 검색과 99%를 넘는 일치율을 보였습니다.

왜 그렇게 잘 작동했을까요?

벡터를 이진 값으로 압축하면 정확도가 더 많이 저하될 것으로 예상할 수 있습니다. 그렇게 되지 않는 이유는 Elasticsearch가 데이터 검색을 처리하는 방식에 있습니다.

오늘날 대부분의 임베딩 모델은 크기가 큰 Float32 벡터를 출력합니다. 검색 효율성을 높이기 위해 Elasticsearch는 고차원 벡터에 양자화를 사용합니다. 특히, 9.2 이후로는 기본적으로 BBQ를 사용합니다.

BBQ는 리스코어 메커니즘을 사용합니다.

1. 트래버설: 검색 엔진은 압축(양자화된) 벡터를 사용하여 HNSW 그래프를 빠르게 탐색합니다. 벡터가 작기 때문에 성능 저하 없이 효율적으로 오버샘플링하여 더 많은 후보 목록(예: 거의 비슷한 상위 100개 문서)을 수집할 수 있습니다.
2. 리스코어: 후보 문서가 있으면 해당 문서에 대한 전체 정밀도 값을 검색하여 최종적이고 정확한 순위를 계산합니다.

이는 무거운 작업을 위한 양자화의 속도와 최종 정렬을 위한 부동 소수점의 정밀도, 이 두 가지 장점을 모두 제공합니다.

더 나은 성과를 낼 수 있을까요?

여기에 표시된 결과는 기본 설정과 무작위 데이터 샘플링을 사용한 결과라는 점에 주목할 필요가 있습니다. 이걸 고성능 출발점이라고 생각해 보세요. Jina v5는 강력한 성능을 자랑하지만, 이러한 리콜 점수가 모든 데이터 세트에 대해 "만능 해결책"을 보장하는 것은 아닙니다. 모든 데이터 수집에는 고유한 특성이 있으며, 더 많은 성능을 끌어내기 위해 더 조정할 수는 있지만, 항상 자신의 특정 데이터와 벤치마킹하여 한계가 어디인지 확인해야 합니다.

결론

이것은 매우 작은 규모의 테스트입니다. 하지만 이 연습의 요점은 임베딩 모델이나 BBQ를 구체적으로 측정하는 것이 아니라, 최소한의 설정으로 데이터 세트의 리콜을 쉽게 측정하는 방법을 보여주기 위한 것입니다.

자신의 데이터로 이 테스트를 실행하려면 여기에서 노트북을 확인하여 직접 시도해 보세요.

확장 프로그램은 여기에서 오픈 소스 프로젝트로 제공됩니다.

Gemini CLI 소개 및 설치 방법

Gemini CLI는 Google의 Gemini 모델을 명령줄로 직접 가져오는 오픈 소스 AI 에이전트입니다. 개발자가 터미널을 통해 AI와 상호 작용하여 코드 생성, 파일 편집, 셸 명령 실행, 웹 정보 검색 등의 작업을 수행할 수 있습니다.

Gemini CLI는 일반적인 채팅 인터페이스와 달리 로컬 개발 환경과 통합되어 프로젝트 컨텍스트를 이해하고, 파일을 수정하고, 빌드나 테스트를 실행하고, 워크플로우를 터미널 내에서 직접 자동화할 수 있습니다. 이러한 특징 덕분에 개발자, 사이트 신뢰성 엔지니어(SRE)뿐만 아니라 명령줄 워크플로우를 벗어나지 않고 AI 기반 코딩 및 자동화를 원하는 엔지니어에게 유용합니다.

Gemini CLI는 여러 패키지 관리자를 사용하여 설치할 수 있습니다. 가장 일반적인 방법은 npm을 사용하는 것입니다:

npm install -g @google/gemini-cli

다른 설치 옵션을 알고 싶다면 공식 설치 페이지를 참조하세요.

설치 후, 다음 명령어로 CLI를 실행하세요.

gemini

그림 1과 같은 화면이 표시됩니다.

Elasticsearch를 구성합니다

Elasticsearch 인스턴스가 실행 중이어야 합니다. 모델 컨텍스트 프로토콜(MCP) 서버를 사용하려면 Kibana 9.3+ 버전이 설치되어 있어야 합니다. 아래 설명된 Elasticsearch 쿼리 언어(ES|QL) 스킬(esql)을 사용하려면 Kibana가 없어도 됩니다.

Elastic Cloud에서 무료 체험을 활성화하거나 start-local 스크립트를 사용해 로컬에 설치할 수 있습니다.

curl -fsSL https://elastic.co/start-local | sh

이 명령을 실행하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Gemini CLI 설정에 사용할 API 키가 생성됩니다.

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

온프레미스 Elasticsearch를 사용 중인 경우(예: start-local 사용), Elastic Agent Builder를 MCP와 함께 사용하려면 대규모 언어 모델(LLM)을 연결해야 합니다. 이 문서 페이지를 읽으면 다양한 옵션을 파악할 수 있습니다.

Elastic Cloud(또는 서버리스)를 사용하는 경우 이미 사전 구축된 LLM 연결이 제공됩니다.

Elasticsearch 확장 프로그램 설치

Elasticsearch 확장 프로그램을 Gemini CLI에 설치하려면 다음 명령어를 사용하세요.

gemini extensions install https://github.com/elastic/gemini-cli-elasticsearch

Gemini를 열고 다음 명령어를 실행하면 확장 프로그램이 성공적으로 설치되었는지 확인할 수 있습니다.

/extensions list

Elasticsearch 확장 프로그램을 사용할 수 있는지 확인할 수 있습니다.

MCP 통합을 사용하려면 Elasticsearch 9.3 이상 버전이 설치되어 있어야 합니다. Kibana에서 가져온 MCP 서버 URL이 필요합니다.

• 에이전트에서 MCP 서버 URL 가져오기 > 모든 도구 보기 > MCP 관리 > MCP 서버 URL 복사
• 표시되는 URL: https://your-kibana-instance/api/agent_builder/mcp

Elasticsearch 엔드포인트 URL이 필요합니다. 일반적으로 이것은 Kibana Elasticsearch 페이지 상단에 보고됩니다. start-local로 Elasticsearch를 실행 중인 경우, start-local .env 파일의 ES_LOCAL_URL 키에 이미 엔드포인트가 있습니다.

API 키도 필요합니다. Elasticsearch를 start-local로 실행 중인 경우, 이미 ES_LOCAL_API_KEY가 start-local.env 파일에 있습니다. 그렇지 않은 경우, 여기에 설명된 대로 Kibana 인터페이스를 사용하여 API 키를 생성할 수 있습니다.

• Kibana: Stack Management > Security > API 키 > API 키 생성
• API 키에 대해 읽기 권한만 설정하여 여기에 보고된 대로 feature_agentBuilder.read 권한을 활성화할 것을 권장합니다.
• 인코딩된 API 키 값을 복사합니다.

셸에서 필요한 환경 변수를 설정하세요.

export ELASTIC_URL="your-elasticsearch-url"
export ELASTIC_MCP_URL="your-elasticsearch-mcp-url"
export ELASTIC_API_KEY="your-encoded-api-key"

예제 데이터 세트 설치하기

Kibana에서 제공되는 eCommerce orders 데이터 세트를 설치할 수 있습니다. 이 데이터 세트에는 kibana_sample_data_ecommerce라는 단일 인덱스가 포함되어 있으며 전자상거래 웹사이트의 4,675개 주문 정보를 담고 있습니다. 각 주문에는 다음과 같은 정보가 포함되어 있습니다.

• 고객 정보(이름, ID, 생년월일, 이메일 등)
• 주문 날짜
• 주문 ID
• 제품(가격, 수량, ID, 카테고리, 할인, 기타 정보를 포함한 전체 제품 목록)
• SKU.
• 총액(세전, 세후)
• 총 수량
• 지리 정보(도시, 국가, 대륙, 위치, 지역).

샘플 데이터를 설치하려면 Kibana의 통합 페이지를 열고(상단 검색창에서 '통합'을 검색) "Sample Data"를 설치하세요. 자세한 내용은 여기 설명서를 확인하세요.

이 글의 목표는 Gemini CLI를 설정해 Elasticsearch에 연결하고 kibana_sample_data_ecommerce 인덱스와 손쉽게 상호작용하는 방법을 보여주는 것입니다.

Elasticsearch MCP를 사용하는 방법

Gemini에서 다음 명령을 사용하여 연결을 확인할 수 있습니다:

/mcp list

그림 2와 같이 elastic-agent-builder가 활성화된 것을 확인할 수 있습니다.

Elasticsearch는 기본 도구 세트를 제공합니다. 여기에서 설명을 참조하세요.

이 도구로 Elasticsearch와 상호 작용하며 다음과 같은 질문을 할 수 있습니다.

• Give me the list of all the indexes available in Elasticsearch.
• How many customers are based in the USA in the kibana_sample_data_ecommerce index of Elasticsearch?

질문에 따라 Gemini는 하나 이상의 도구를 사용하여 답변을 시도합니다.

/elastic 명령어

Gemini CLI의 Elasticsearch 확장 프로그램에서 /elastic 명령어를 추가했습니다.

/help 명령을 실행하면 사용 가능한 모든 /elastic 옵션이 표시됩니다(그림 3).

이 명령어들은 elastic-agent-builder MCP 서버의 특정 도구를 직접 실행하고자 할 때 유용할 수 있습니다. 예를 들어 다음 명령어를 사용하면 kibana_sample_data_ecommerce의 매핑을 얻을 수 있습니다.

/elastic:get-mapping kibana_sample_data_ecommerce

이러한 명령은 Gemini 모델에 의존하여 실행할 도구를 결정하는 대신, 특정 도구를 실행하는 바로가기 역할을 합니다.

Elasticsearch 스킬 사용 방법

이 확장 기능에는 ES|QL용 에이전트 기술과 Elasticsearch에서 사용할 수 있는 Elasticsearch 쿼리 언어가 함께 제공됩니다. Agent Skills는 Gemini CLI와 같은 AI 코딩 에이전트에 특정 작업에 대한 사용자 지정 지침을 제공하는 개방형 형식입니다. 점진적 공개라는 개념을 사용하여 초기 시스템 프롬프트에 스킬에 대한 간략한 설명만 추가합니다. 에이전트에게 Elasticsearch 쿼리와 같은 작업을 수행하도록 요청하면 에이전트는 해당 요청을 관련 스킬과 연결하고 자세한 지침을 동적으로 불러옵니다. 이는 토큰 예산을 관리하면서 AI에 필요한 컨텍스트를 정확하게 제공하는 효율적인 방법입니다.

esql 스킬은 Gemini CLI가 클러스터에 직접 ES|QL 쿼리를 작성하고 실행할 수 있도록 설계되었습니다. ES|QL은 데이터 탐색, 로그 분석 및 집계를 매우 직관적으로 수행할 수 있는 강력한 파이프 쿼리 언어입니다. 이 스킬을 활성화하면 ES|QL 구문을 찾아볼 필요가 없습니다. Gemini CLI에 데이터에 대한 자연어 질문을 입력하기만 하면, 에이전트가 나머지 작업을 처리합니다.

실행은 터미널에서 실행되는 간단한 curl 명령어를 사용하여 수행됩니다. 이것이 가능한 것은 Elasticsearch가 어떤 아키텍처에도 쉽게 통합할 수 있는 풍부한 REST API 세트를 제공하기 때문입니다.

esql 스킬 제공 내용:

• 인덱스 및 스키마 검색: 에이전트가 스킬의 기본 제공 도구를 사용하여 사용 가능한 인덱스를 나열하고 필드 매핑을 가져올 수 있습니다. 예를 들어 전자상거래 데이터세트에 대한 쿼리를 작성하기 전에 에이전트가 kibana_sample_data_ecommerce 스키마 검사를 실행해서 사용 가능한 필드(예: taxful_total_price 또는 category)를 파악할 수 있습니다.
• 원활한 자연어 번역: 이 스킬은 에이전트에 단순한 참조 매뉴얼을 넘어 사용자 의도를 해석할 수 있는 구체적인 가이드를 제공합니다. '서비스별 평균 응답 시간 표시'와 같은 자연어 요청을 입력하면 에이전트가 스킬에 내장된 패턴 매칭 기능을 사용하여 사용자가 입력한 내용을 올바른 ES|QL 집계, 필터 및 명령으로 즉시 변환합니다.
• 자체 수정: 만일 타입 불일치 또는 구문 오류로 인해 쿼리가 실패하면, 스킬은 생성된 쿼리와 정확한 Elasticsearch 오류 메시지를 반환하여 에이전트가 즉시 쿼리를 수정하고 사용자가 개입하지 않아도 다시 시도할 수 있게 됩니다.

esql 스킬은 elastic-agent-builder MCP 서버에서도 도구로 제공되므로 이 서버를 잠시 비활성화해야 합니다. 다음 명령어를 사용하여 비활성화할 수 있습니다.

/mcp disable elastic-agent-builder

그런 다음 Gemini CLI에 다음과 같은 프롬프트를 입력하기만 하면 됩니다.

Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index

에이전트가 수행하는 작업:

• esql 스킬의 필요성을 인식해야 합니다.
• kibana_sample_data_ecommerce 스키마를 확인하세요.
• FROM kibana_sample_data_ecommerce | STATS total_revenue = SUM(taxful_total_price) BY category.keyword | SORT total_revenue DESC | LIMIT 5 등 ES|QL 쿼리를 구성합니다.
• Elasticsearch API에 대해 쿼리 작업을 실행하세요.
• 터미널에서 바로 최종 답을 제시합니다.

여기서는 이전 프롬프트에 대한 Gemini의 응답 사례를 보고했습니다.

───────────────────────────────────────────────────────────
> Find the top 5 product categories by total sales revenue in the kibana_sample_data_ecommerce index   ───────────────────────────────────────────────────────────
✓  Activate Skill "esql": Interact with Elasticsearch using ES|QL and curl. Use when querying, managing indices,  …
Skill esql activated. Resources loaded from /home/user/.gemini/extensions/elasticsearch/skills/esql: 
Showing up to 200 items (files + folders).                                                                     /home/user/.gemini/extensions/elasticsearch/skills/esql/                                                            ├───SKILL.md 
└───references/
├───esql-reference.md 
├───generation-tips.md 
└───query-patterns.md

✦ I will start by exploring the mapping of the kibana_sample_data_ecommerce index to identify the fields for product category and sales revenue. Then, I will construct and execute an ES|QL query to determine the top 5 product categories by total sales revenue.

✓  Shell curl -s "${ELASTIC_URL%/}/kibana_sample_data_ecommerce/_mapping" -H "Authorization: ApiKey $(printenv ELAS…                                                                                                                       {  
   "kibana_sample_data_ecommerce": { 
     "mappings": { 
       "properties": {
         "category": { 
           "type": "text", 
           "fields": {
             "keyword": {
               "type": "keyword"
             }
           }
         }, 
         "currency": {
           "type": "keyword"
         }, 

✦ Okay, I have the mapping. The category is products.category.keyword and sales revenue is taxful_total_price. I'll now execute the ES|QL query to get the top 5 categories by revenue.

✓  Shell curl -s -X POST "${ELASTIC_URL%/}/_query" \  -H "Authorization: ApiKey $(printenv ELASTIC_API_KEY)" \  -H …
{ 
   "took": 62,
   "is_partial": false, 
   "completion_time_in_millis": 1772805644164,
   "documents_found": 4675,
   "values_loaded": 12084, 
   "start_time_in_millis": 1772805644102, 
   "expiration_time_in_millis": 1773237644087,  
   "columns": [ 
     { 
       "name": "total_revenue",    
       "type": "double"  
     }, 
     {   
       "name": "products.category.keyword",

✦ The query for top 5 product categories by revenue was successful. I'll format the returned JSON values into a   user-friendly list.

 ✓  Shell 
                             
 Top 5 product categories by total sales revenue: 
 1. Men's Clothing: 149393.91
 2. Women's Clothing: 135099.91
 3. Women's Shoes: 105479.17
 4. Men's Shoes: 91797.92
 5. Women's Accessories: 60830.31 

✦ I've found the answer; now I'll format it for clarity.

 ✓  Shell 

 Here are the top 5 product categories by total sales revenue:                                                        
                                                                      
 | Rank | Category              | Total Revenue | 
 |------|-----------------------|---------------| 
 | 1    | Men's Clothing        | 149,393.91    |
 | 2    | Women's Clothing      | 135,099.91    |
 | 3    | Women's Shoes         | 105,479.17    |
 | 4    | Men's Shoes           | 91,797.92     | 
 | 5    | Women's Accessories   | 60,830.31     | 

✦ I've formatted and presented the answer. I'm finished.
 ───────────────────────────────────────────────────────────

Gemini 모델이 최종 응답을 도출하는 모든 단계를 보여주는 방식은 흥미로운 부분입니다. 여기에서 모델의 추론 과정에 대한 스킬의 영향력을 확실하게 확인할 수 있습니다. 모델이 스킬을 사용하거나 셸 명령을 실행해야 한다고 처음 인식할 때, 휴먼 인 더 루프 방식을 사용하여 권한을 요청합니다.

esql 스킬은 스키마 발견, 쿼리 생성 및 실행과 같은 복잡한 작업을 처리함으로써 답을 얻는 과정의 메커니즘이 아닌 답 자체에만 집중할 수 있도록 도와줍니다. 필요한 데이터를 제대로 된 형식으로 터미널에서 바로 얻을 수 있습니다. 단 한 줄의 구문도 작성하거나 다른 애플리케이션으로 컨텍스트를 전환할 필요도 없습니다.

결론

이 글에서는 최근에 출시한 Gemini CLI용 Elasticsearch 확장 기능을 소개했습니다. 이 확장 프로그램을 사용하면 Gemini와 Elastic Agent Builder에서 제공하는 Elasticsearch MCP 서버(버전 9.3.0부터 사용 가능)를 이용하여 Elasticsearch 인스턴스와 상호 작용할 수 있습니다. /elastic 명령어도 사용할 수 있습니다.

더불어, 이 확장에는 사용자의 요청을 자연어에서 ES|QL 쿼리로 변환하는 esql 스킬도 포함되어 있습니다. 이 기술은 MCP 서버를 사용할 수 없는 경우 특히 유용합니다. 기본 통신이 터미널에서 실행되는 간단한 curl 명령에 의해 이루어지기 때문입니다. Elasticsearch는 어떤 프로젝트에도 쉽게 통합될 수 있는 풍부한 REST API 세트를 제공합니다. 이는 에이전틱 AI 애플리케이션을 개발할 때 특히 유용합니다.

Gemini CLI 확장 기능에 대한 자세한 내용은 여기 프로젝트 리포지토리에서 확인하세요.

이것이 바로 Elastic이 Elastic Agent Skills를 오픈 소스로 공개하는 이유입니다. 이는 Elasticsearch, Kibana, Elastic Observability 및 Elastic Security를 위한 네이티브 플랫폼 전문 지식입니다. 현재 사용 중인 에이전트 런타임에 이 스킬들을 추가해 보세요. 수많은 구문을 추측만 하던 '범용' 수준의 에이전트를 Elastic 엔지니어링 팀만큼의 아키텍처 표준을 구사하는 전문가로 업그레이드할 수 있습니다. 이번 초기 기술 프리뷰 버전은 Elastic Cloud Serverless와 최상의 호환성을 갖춘 스킬을 중심으로 제공됩니다. 하지만 빠른 시일 내에 이전 스택 버전에 대한 지원도 넓혀나갈 예정입니다.

또한 Elastic은 이 문제를 양방향에서 해결하고 있습니다. 우선 Elastic 플랫폼 내의 에이전트를 위해, 이제 정식 버전으로 출시된 Elastic Agent Builder를 제공합니다. 이를 통해 데이터 접근 권한을 상속받고 내장된 검색 및 분석 도구를 사용하며 대시보드, 알림 및 조사와 연동되는 AI 에이전트를 생성하고 대화할 수 있습니다. Elastic은 플랫폼 내에서 최상의 에이전트 중심 경험을 구현하기 위해 전력을 다하고 있습니다. 하지만 모든 에이전트가 Elastic 내부에서만 활동하는 것은 아닙니다. 여러분의 팀은 이미 Cursor, Claude Code 또는 다른 런타임을 사용하고 있을 것이며 이 에이전트들 역시 Elastic을 제대로 활용할 수 있어야 합니다. 바로 그 지점에서 Agent Skills가 핵심적인 역할을 수행합니다.

AI 에이전트가 전문 플랫폼에서 어려움을 겪는 이유

대규모 언어 모델(LLM)은 다방면에 능한 팔방미인과 같습니다. 학습 데이터의 예제가 풍부하다 보니 Python을 작성하거나 Kubernetes 매니페스트를 설명하고 React 컴포넌트를 리팩토링하는 일을 능숙하게 해냅니다. 그러나 전용 쿼리 언어와 방대한 API 체계 그리고 해당 도메인의 특수한 설계 원칙을 준수해야 하는 전문 플랫폼 작업에서는 예외 없이 한계를 드러내고 맙니다.

Elasticsearch의 경우 이러한 간극은 다음과 같이 구체적으로 나타납니다.

• Elasticsearch 쿼리 언어(ES|QL)는 새로운 영역입니다. LLM은 SQL 위주로 집중 학습되었지만 ES|QL은 구문과 함수, 의미 체계가 전혀 다른 파이프 기반의 쿼리 언어입니다. 이 때문에 에이전트는 겉보기엔 그럴듯하지만 실제로는 구문 분석이 되지 않는 쿼리를 작성하는 경우가 많습니다. WHERE을 | WHERE으로 착각하거나 존재하지 않는 함수를 임의로 만들어내고 파이프 중심의 쿼리 구성 방식을 완전히 놓치기도 합니다.
• API 체계는 방대하고 복잡합니다. Elasticsearch, Kibana 및 Elastic Security는 검색, 수집, 알림, 탐지 규칙, 케이스 관리, 대시보드 등 전반에 걸쳐 수백 개의 API를 제공합니다. 보편적인 학습 데이터만 갖춘 에이전트는 어떤 엔드포인트를 호출할지, 요청 본문은 어떻게 구성할지, 응답은 어떻게 처리할지를 추측에 의존할 수밖에 없습니다. 그리고 이러한 추측이 빈번하게 빗나가면서 결국 사용자의 신뢰를 떨어뜨리게 됩니다.
• 학습 데이터에는 실무 노하우가 반영되어 있지 않습니다. 언제 semantic_text를 사용하고 언제 커스텀 임베딩 파이프라인을 구축할지, 10GB 크기의 CSV 수집 파이프라인은 어떻게 구성해야 할지, 혹은 MITRE ATT&CK 기술에 적합한 탐지 규칙 구문은 무엇인지와 같은 고민은 학습 데이터만으로 해결하기 어렵습니다. 범용 에이전트에는 잘 정리되고 신뢰할 수 있는 구조를 갖춘 Elastic 전용 지식이 기본적으로 탑재되어 있지 않기 때문입니다. 에이전트가 직접 정보를 찾아낸다 하더라도 가공되지 않은 문서는 숙련된 전문가가 가진 상황별 판단이나 실무 노하우까지 모두 담아내지는 못합니다.

그 결과 개발자는 직접 코드를 짤 때보다 에이전트의 결과물을 수정하는 데 더 많은 시간을 허비하게 됩니다. 이는 우리가 기대했던 경험이 전혀 아닙니다.

에이전트 스킬: 에이전트를 위해 패키징된 플랫폼 지식

Agent Skills는 에이전트 런타임이 동적으로 로드할 수 있는 지침, 스크립트 및 참조 자료가 포함된 독립적인 디렉터리입니다. 스킬이 활성화되면 에이전트는 적절한 시점에 적절한 컨텍스트(쿼리 구문, API 패턴, 검증 논리, 실제 실행 사례 등)에 접근할 수 있게 되며 이를 통해 첫 시도만으로도 작업을 정확하게 완료할 수 있습니다.

각 스킬은 오픈 소스인 agentskills.io 사양을 따릅니다. 이는 메타데이터와 구조화된 지침이 담긴 SKILL.md 파일이 포함된 폴더 형태입니다. 독자적인 포맷도 벤더 종속성도 없습니다. 스킬은 Cursor, Claude Code, GitHub Copilot, Windsurf, Gemini CLI, Cline, Codex를 비롯하여 다양한 에이전트 런타임에 걸쳐 작동합니다.

초기 v0.1.0 릴리스 포함 내용

첫 번째 스킬 세트는 Elastic Stack의 다섯 가지 영역을 아우릅니다.

• Elasticsearch API와 상호 작용(검색, 인덱싱, 클러스터 관리)
• Kibana 콘텐츠 구축 및 관리(대시보드, 알림, 커넥터 등)
• Elastic Observability를 위한 도메인 전문성
• Elastic Security를 위한 도메인 전문성
• Agent Builder 내에서 효과적인 에이전트 만들기

스킬의 결합성

스킬은 거대한 단일 구조가 아닙니다. 설계 단계부터 모듈화되어 있습니다. 에이전트는 현재 수행 중인 작업에 필요한 스킬만 로드합니다. ES|QL 쿼리를 작성 중인가요? ES|QL 스킬이 활성화됩니다. 그 결과로 대시보드를 만들어야 하나요? 대시보드 스킬이 작업을 넘겨받습니다. 애플리케이션의 상태를 평가 중인가요? 서비스 상태 스킬이 작동합니다. 보안 알림을 조사 중인가요? 분석 스킬이 조사의 진행 단계에 따라 케이스 관리 및 대응 스킬로 이어집니다.

이러한 결합성은 모든 것을 한꺼번에 해결하려는 거대한 단일 프롬프트가 필요 없음을 의미합니다. 각 스킬은 해당 도메인에 필요한 만큼의 컨텍스트만을 담고 있으며 그 이상도 그 이하도 아닙니다.

검색 및 AI 애플리케이션을 구축하는 개발자를 위한 스킬

Elasticsearch에 데이터를 로드하거나 쿼리를 작성하고 인덱스를 마이그레이션할 때 에이전트 스킬은 코드를 생성하고 오류에 부딪힌 뒤 원인을 찾기 위해 문서를 검색해야 하는 과정을 줄여줍니다.

에이전트에게 CSV 파일 로드를 요청하면 에이전트는 백프레셔를 처리하고 데이터에서 매핑을 추론하는 스트리밍 수집 도구를 사용합니다. 이는 대용량 파일을 처리하자마자 메모리 부족을 일으키는 임시방편의 수동 _bulk 루프가 아닙니다. ES|QL로 쿼리하도록 요청하면 에이전트는 실제 인덱스 이름과 필드 스키마를 찾아낸 뒤 정확한 구문, 적절한 집계, 버전별 기능을 반영한 유효한 파이프 쿼리를 작성합니다. 세 번씩 디버깅을 반복해야 하는 SQL의 흉내만 낸 추측성 답변이 아닙니다. 클러스터 간 재인덱싱을 요청하면 에이전트는 명시적 매핑으로 대상 인덱스를 생성하고 처리량 최적화를 위한 설정 튜닝까지 수행합니다. 또한 작업을 비동기로 실행하고 완료 후 운영 설정을 복구하는 전체 운영 워크플로우를 따릅니다. 숙련된 운영자가 수행할 단계들을 절반이나 건너뛰는 단순한 _reindex 호출이 아닙니다.

사용자가 직접 수정해야 하는 그럴싸한 시작점만 제공하는 에이전트 대신 운영 방식을 내재화하여 실행 가능한 결과물을 만드는 에이전트를 얻게 됩니다.

Elastic Agent Skills 사용에 따른 주요 변화 예시

보안 팀을 위한 스킬

보안 팀은 매일 알림 심사, 탐지 규칙 최적화, 케이스 관리와 같은 동일한 운영 워크플로우를 반복합니다. Agent Skills는 이러한 절차적 지식을 내재화하여 AI 에이전트가 정확한 필드 이름으로 적절한 API를 올바른 순서에 따라 호출하며 워크플로우를 수행할 수 있게 합니다. IDE를 벗어나지 않고 초기 설정부터 실제 데이터가 완비된 Elastic Security 환경을 구축하는 실습 과정은 AI 에이전트로 Elastic Security 시작하기 가이드를 참조하세요.

통합 가시성 및 운영 팀을 위한 스킬

Elastic Observability를 위한 새로운 Agent Skills는 복잡한 시스템의 계측, SLO 관리, 복잡한 데이터 선별, 서비스 상태 평가 등에 드는 운영상의 수고를 줄여줍니다. AI 에이전트에 Elastic의 네이티브 전문 지식을 직접 내재화함으로써 운영 팀은 간단한 자연어만으로도 복잡한 통합 가시성 워크플로우를 실행할 수 있습니다. 이를 통해 SRE 및 운영 팀은 장애를 더 빠르게 해결하고 시스템의 신뢰성을 더욱 쉽게 유지할 수 있습니다. 자세한 내용은 블로그에서 확인해 보세요.

오픈 소스, 오픈 사양, 커뮤니티 중심

Elastic은 에이전트의 지식이 공개되어야 한다고 믿기에 Agent Skills를 Apache 2.0 라이선스로 출시합니다. 각 스킬이 따르는 agentskills.io 사양은 Elastic의 독자적인 포맷이 아닌 오픈 표준입니다. Elastic은 에이전트 스킬이 폐쇄적인 환경이 아닌 커뮤니티가 함께 만들어가는 노력이 되기를 바랍니다.

더 큰 그림의 일부

Agent Skills는 Elasticsearch를 현존하는 가장 에이전트 친화적인 데이터 플랫폼으로 만들기 위한 광범위한 이니셔티브의 일환입니다. Elasticsearch 플랫폼 기반의 에이전트를 위해 Agent Builder는 데이터 액세스 제어 및 권한을 상속받아 한 단계 더 진화된 기능을 제공합니다. 또한 검색 및 분석을 위한 내장 및 커스텀 도구를 제공하며 사용자가 대시보드, 알림 및 조사 워크플로우와 함께 컨텍스트에 맞게 에이전트와 상호 작용할 수 있도록 지원합니다. 마지막으로 Agent Builder에 스킬 지원 기능이 곧 추가될 예정입니다. 이를 통해 개발자는 Elastic Agent Skills뿐만 아니라 다른 소스의 스킬까지 유연하게 활용하여 Elasticsearch 플랫폼에서 보안이 강화되고 컨텍스트가 풍부한 채팅 및 자동화를 구현할 수 있게 됩니다.

Elastic 외부의 다양한 환경에서 운영되는 에이전트를 위해 Elastic은 다음과 같은 오픈 생태계에 투자하고 있습니다.

• 모델 컨텍스트 프로토콜(MCP) 서버 확장: 현재의 검색, ES|QL, 인덱스 작업을 넘어 더 많은 도구를 사용할 수 있도록 Agent Builder의 MCP 엔드포인트를 확장합니다.
• 인증 방식 개선: 수동으로 API 키를 복사하고 붙여넣는 과정을 없애는 것을 목표로 에이전트가 더욱 쉽고 안전하게 연결할 수 있도록 개선합니다.
• LLM이 이해하기 쉬운 문서: 에이전트가 스스로 Elastic API를 탐색하고 이해할 수 있도록 llms.txt 및 AGENTS.md 파일을 게시합니다.
• 에이전트 워크플로우용 명령줄 인터페이스(CLI): 연결 관리 및 일반적인 작업을 에이전트 친화적으로 만들어 주는 명령줄 도구를 제공합니다.

스킬은 현재 바로 사용할 수 있는 계층이며 나머지도 곧 추가될 예정입니다.

시작하기

시작하기 전에: AI 코딩 에이전트는 실제 자격 증명과 실제 셸 액세스 권한으로 작동하며 대개 에이전트를 실행하는 사용자의 모든 권한을 가집니다. 이러한 에이전트가 보안 워크플로우에 투입될 경우 그 위험성은 더욱 커집니다. 탐지 로직, 대응 조치 및 민감한 텔레메트리에 대한 접근 권한을 자동화된 시스템에 넘겨주는 셈이기 때문입니다. 조직마다 위험 수용 범위는 다릅니다. AI 기반 보안 워크플로우를 활성화하기 전에 에이전트가 어떤 데이터에 접근할 수 있는지, 어떤 작업을 수행할 수 있는지 그리고 예기치 않게 동작할 경우 어떤 영향을 미칠지 평가해야 합니다.

Elastic Agent Skills를 에이전트 런타임에 설치합니다.

npx skills add elastic/agent-skills

이 명령은 설치된 에이전트 런타임을 자동으로 감지하여 올바른 구성 디렉터리에 스킬을 배치합니다. 이후 에이전트는 해당 스킬을 자동으로 인식합니다.

또한 스킬 카탈로그를 직접 탐색하여 스킬 폴더를 에이전트의 구성 디렉터리에 복사함으로써 개별 스킬을 수동으로 설치할 수도 있습니다.

아직 Elasticsearch 클러스터가 없으신가요? Elastic Cloud 무료 체험판을 시작해 보세요. 약 1분이면 모든 설정이 완료된 환경을 준비할 수 있습니다.

프로젝트 살펴보기:

• Agent Skills 저장소
• agentskills.io 사양
• Elasticsearch 문서
• Elastic Cloud 무료 체험판

이전 게시물에서 앞서 보았듯이, 함수 호출이 제공하는 일관성은 단순한 최적화가 아닌 필수 사항입니다. 평가 루프에서 구조적 오류를 제거하자 표준 시나리오(예: 티어 4 데이터 세트)의 결과가 크게 향상되었습니다.

하지만 아직 답변이 필요한 질문도 분명히 남아 있습니다.

상황이 아주 복잡해질 때도 이 접근 방식이 여전히 효과가 있을까요?

실제 엔티티 해석은 단순한 경우로 인해 실패하는 일이 거의 없습니다. 이름이 언어, 문화, 문자 체계, 시대, 조직 경계를 넘나들 때 실패하게 됩니다. 사람들이 이름 대신 직함으로 언급되거나, 회사가 이름을 바꾸거나, 음역이 일관되지 않거나, 철자가 아니라 컨텍스트만이 실제 세계의 엔티티와 연결되는 유일한 요소일 때 실패하게 됩니다.

그래서 이 시리즈의 마지막 포스팅에서 시스템에 '궁극의 도전'이라는 과정을 진행했습니다.

이것이 궁극적인 도전인 이유는 무엇입니까?

이전 평가에서는 점점 더 복잡한 데이터 세트를 사용하여 시스템을 테스트했습니다. 이전 게시물에서 논의된 티어 4에 도달했을 때는 이미 별명, 직함, 다국어 이름 및 의미 참조의 혼합을 다루고 있었습니다. 해당 테스트 결과, 아키텍처 자체는 견고했음에도 특히 잘못된 JSON 형식과 같은 신뢰성 문제로 인해 재현율이 저해되는 것으로 나타났습니다.

함수 호출이 구현됨에 따라 마침내 안정적인 기반을 마련할 수 있었습니다. 덕분에 더 흥미로운 질문을 할 기회가 생겼습니다.

하나의 통합 파이프라인이 여러 종류의 엔티티 해석 문제를 동시에 처리할 수 있을까요?

궁극의 과제 데이터 세트는 바로 그러한 차원을 시험하기 위해 설계되었습니다.

별명이나 음역과 같은 단일한 문제에 집중하는 대신, 이 데이터 세트는 다음과 같은 50개 이상의 다양한 과제 유형을 결합합니다.

• 문화적 지명 관습
• 직함 기반 참조
• 비즈니스 관계와 역사적 이름 변경 사항.
• 다국어 및 교차 스크립트 언급
• 위의 여러 가지가 혼합된 복합 과제입니다.

무엇보다 중요한 것은 이것이 단 하나의 제한적인 사용 사례에 대한 최적화가 아니라는 것입니다. 엔티티 간에 규칙이 변경될 때 설계 패턴이 유지되는지 테스트하는 것이 중요한 부분입니다.

데이터 세트 개요

궁극의 과제 데이터 세트는 다음과 같이 구성됩니다.

• 사람, 조직, 기관이 포함된 50개 엔티티.
• 다양한 구조와 언어적 복잡성을 지닌 약 60개의 기사.
• 51개의 뚜렷한 과제 카테고리가 다음과 같이 넓게 그룹화됩니다.
  • 문화적 지명 관습
  • 직함 및 전문적 맥락.
  • 비즈니스 및 조직적 관계
  • 다국어 및 음역 문제.
  • 결합 및 극단 시나리오

이 시리즈의 초반부에서 생성형 AI(GenAI)를 사용하여 데이터 세트를 생성하는 것에 장단점이 있다는 것을 확인했습니다. 생성형 AI가 없으면 충분히 크고 다양한 테스트 데이터를 구성하는 것이 매우 어려워집니다. 그러나 제어하지 않으면 모델이 작업을 지나치게 쉽게 만드는 경향이 있습니다.

초기 세대 합격 예시를 보면 모델이 블라디미르 푸틴의 명시적 별칭으로 '러시아 대통령'과 같은 구문을 포함시켰다는 사실이 발견되었습니다. 현재로서는 합리적으로 보일 수 있지만, 이는 상황별 해결 테스트의 목적을 무효화합니다. 기사가 1990년대 러시아에 대해 논의하고 있다면 어떻게 될까요? 시스템은 하드코딩된 별칭에 의존하지 않고 컨텍스트에서 올바른 엔티티를 추론해야 합니다.

그러한 이유로, 이 데이터 세트는 지름길이 통하지 않도록 의도적으로 설계되었습니다. 별칭은 시스템이 의미를 유추해야 할 때 명시적으로 나열되지 않습니다. 설명적 구문이 엔티티에 사전 연결되어 있지 않습니다. 정확한 일치는 단순한 로컬 텍스트가 아닌 문서 수준의 컨텍스트에 의존하기도 합니다.

중요 사항: 다양한 시나리오에서 시스템의 기능을 시연하는 것이지만 이는 교육용 프로토타입임을 알려드립니다. 실제 제재 대상 엔티티 모니터링을 처리하는 프로덕션 시스템에는 추가적인 검증, 규정 준수 점검, 감사 추적 및 민감한 사용 사례에 대한 전문적인 처리가 필요합니다.

이러한 시나리오가 어려운 이유

이 시리즈의 첫 번째 게시물에서 “새로운 Swift 업데이트가 도착했습니다!”라는 간단하지만 모호한 예를 소개했습니다. 문제는 'Swift'가 상황에 따라 실제 세계의 여러 엔티티로 해석될 수 있다는 것입니다. 이 예시는 더 큰 진실을 드러냅니다. 자연어가 본질적으로 모호하다는 것이죠.

따라서 엔티티 해석은 단순히 스트링 일치 문제가 아닙니다. 인간은 일상적으로 공유된 지식, 문화적 규범, 상황적 맥락에 의존하여 참조를 해결하며, 그렇게 하고 있다는 사실을 거의 인지하지 못합니다.

고려해야 할 일반적인 케이스:

• 지정학 및 시대적 컨텍스트가 없다면 '대통령'과 같은 직함은 의미가 없습니다.
• 회사 이름은 기사 작성 시기에 따라 모회사, 자회사 또는 이전 브랜드를 가리킬 수 있습니다.
• 사람의 이름은 언어와 문화에 따라 다른 순서, 문자 체계 또는 음역으로 표현될 수 있습니다.
• 동일한 문구가 다른 컨텍스트에서 다른 엔티티를 정당하게 참조할 수 있으며, 시스템은 일치 항목을 수락하는 것만큼 자신 있게 거부할 수 있어야 합니다.

이러한 모든 상황을 깔끔하게 처리할 수 있는 단일 규칙 세트는 없습니다. 그래서 이 프로토타입은 우려 사항을 매우 철저하게 분리합니다.

• Elasticsearch는 후보 공간을 효율적이고 투명하게 좁힙니다.
• LLM은 판단이 필요하고 스스로 설명해야 하는 경우에만 사용됩니다.
• 검색과 추론은 여전히 뚜렷하게 구분됩니다.

과제 유형이 다양해질수록 이러한 분리가 더욱 중요해집니다.

시스템이 특별 사례 없이 다양성을 처리하는 방식

이 평가에서 가장 흥미로운 결과 중 하나는 변하지 않은 부분입니다.

• 일본어 이름에 대한 특별한 로직을 추가하지 않았습니다.
• 아랍어 부칭에 대한 사용자 지정 규칙을 추가하지 않았습니다.
• 과거 회사 이름에 하드코딩된 매핑을 추가하지 않았습니다 .

대신 이 시스템은 이 시리즈에서 앞서 소개된 것과 동일한 핵심 요소에 의존했습니다.

• 시맨틱 검색을 위해 인덱싱된 컨텍스트가 풍부한 엔티티
• Elasticsearch 내 하이브리드 검색(정확성, 별칭, 의미론적 검색)
• 잘 정의된 소규모 후보 일치 집합
• 함수 호출 및 최소 스키마에 의해 제한되는 LLM 판단

이는 시스템의 유연성이 점점 늘어나는 규칙 집합이 아니라 표현과 구조에서 온다는 것을 시사합니다.

시스템이 성공하는 경우는 올바른 후보가 검색되고, LLM이 참조가 특정 엔티티에 매핑되거나 매핑되지 않는 이유를 설명할 충분한 맥락을 제공하기 때문입니다.

결과: 성능은 어떠했습니까?

궁극의 과제 데이터 세트에서 시스템은 다음과 같은 종합적인 결과를 도출했습니다.

• 정밀도: ~91%
• 재현율: ~86%
• F1 점수: ~89%
• LLM 합격률: ~72%

도전 과제 유형 전반에 걸친 성과

과제 유형별로 결과를 분석하면 강점과 한계가 드러납니다.

가장 강한 성능(100% F1 점수)은 다음과 같은 영역에서 관찰되었습니다.

• 스크립트 간 매칭(키릴 문자, 한국어, 중국어 사업체)
• 히브리어 시나리오(부칭, 전문 직함, 종교 직함, 음역)
• 비즈니스 계층(항공우주, 다각적인 제조, 다사업부 기업)
• 전문직 칭호(학문적, 군사적, 정치적, 종교적).
• 여러 문자 체계를 포함하는 결합된 일본어 시나리오입니다.

강력한 성능(80–99% F1 점수) 포함 사항:

• 국제 정치인(98%)
• 과거 이름 변경 내역(90%)
• 복잡한 비즈니스 계층(89%)
• 일본 회사 이름(93%)
• 교차 문자 체계 음역(86%)
• 아랍어 애칭(86%)

더 까다로운 영역 포함:

• 고급 음역(중국어, 한국어): 0% F1.
• 특정 일본어 시나리오(경어법, 이름 순서, 쓰기 체계 변형): ~67% F1.
• 일부 아랍어 시나리오(회사명, 기관 참조): ~40% F1.

여기서 중요한 것은 이 사례에서 시스템이 어려움을 겪은 이유입니다. 이러한 실패는 전반적인 접근 방식이 고장났기 때문이 아니라 특정 구성 요소, 특히 특정 다국어 시나리오에서 시맨틱 검색에 사용되는 고밀도 벡터 모델의 한계로 인한 것이었습니다.

검색과 판단이 명확하게 분리되어 있기 때문에, 성능 향상을 위해 시스템을 다시 작성할 필요가 없습니다. 보다 뛰어난 다국어 임베딩 모델로 교체하거나, 엔티티 컨텍스트를 강화하거나, 검색 전략을 개선하면 핵심 아키텍처를 변경하지 않고도 이러한 카테고리 전반에 걸쳐 결과를 향상시킬 수 있습니다.

아키텍처 관점에서는 그것이 진정한 성공 지표입니다.

디자인에 대해 알 수 있는 내용

시리즈를 되돌아보면, 몇 가지 패턴이 눈에 띕니다.

• 영리한 매칭보다 준비가 더 중요합니다. 사전에 컨텍스트로 엔티티를 보강하면 이후 모호성을 크게 줄일 수 있습니다.
• LLM은 검색자가 아니라 심사 위원으로서의 가치가 가장 뛰어납니다.검색하라고 요청하는 것보다 일치하는 이유를 설명해달라고 요청하는 것이 훨씬 효과적입니다.
• 신뢰성이 정확성을 뒷받침합니다. 함수 호출은 JSON을 정리하는 것뿐만 아니라, 검색 단계에서 이미 잠재되어 있던 기억력을 끌어내는 역할을 했습니다.
• 일반화가 전문화보다 우수합니다.잘 선택한 소규모 추상화를 통해 사용자 정의 로직 없이 수십 가지 과제 유형을 처리할 수 있었습니다.

이것이 바로 프로토타입이 의도적으로 Elasticsearch 네이티브 방식으로 설계되었고, LLM 사용 방식에 있어서도 의도적으로 보수적인 접근 방식을 취한 이유입니다. 목표는 검색을 대체하는 것이 아니라, 의미가 중요한 상황에서 검색을 설명 가능하게 만드는 것입니다.

결론

궁극의 과제는 완벽한 지표를 추구하기 위한 것이 아니라, 더 근본적인 질문에 답하기 위한 것입니다.

투명한 검색 우선의 LLM 기반 아키텍처가 규칙이나 블랙박스로 전락하지 않고 실제 세계의 엔티티 모호성을 처리할 수 있을까요?

이 교육용 프로토타입의 경우 프로덕션 강화, 규정 준수, 모니터링 및 데이터 품질과 관련된 명확한 주의사항이 있지만 그 답은 '예'입니다. 엔티티 일치가 이루어진 이유를 정당화해야 하는 시스템을 구축하는 경우, 이 패턴을 진지하게 고려할 가치가 있습니다. 이 시리즈를 통해 엔티티 해결이 불가사의하지 할 이유가 없다는 것을 알게 되셨기를 바랍니다. 문제를 제대로 분리하면 엔티티 해결을 이해하고, 측정하고, 개선할 수 있습니다.

이 작업은 또한 더 광범위한 아키텍처 패턴을 제안합니다. 이를 통해 고전적인 Retrieval-Augmented Generation(RAG) 방식의 미미하지만 중요한 진화가 드러납니다. 검색이 생성에 직접 정보를 제공하게 하는 대신, 명시적인 평가 단계를 도입했습니다. LLM이 먼저 사용되어 검색된 후보를 심사하고 무결성을 확인하며 승인된 결과만 생성을 보강하는 것이 허용됩니다. 이를 Generation-Augmented Retrieval-Augmented Generation with Evaluation, 즉 GARAGE라고 생각하시면 됩니다. 이렇게 좋은 약어를 마다할 사람은 없겠죠?

이 패턴이 다른 어떤 사용 사례에 도움이 될 수 있을까요? 신뢰, 투명성 및 변호 가능한 추론이 필요한 시스템이 당연히 후보가 될 것입니다. 이 분야의 향후 작업은 여기서 본 결과만큼이나 매력적일 것입니다. 커뮤니티가 다음에 어떤 방향으로 나아갈지 정말 기대됩니다.

다음 단계: 직접 사용해 보기

궁극의 과제가 실제로 작동하는 모습을 확인하고 싶으세요? 실제 구현, 자세한 설명 및 실습 예제가 포함된 궁극의 과제 노트북을 확인해 보세요.

완전한 엔티티 해석 파이프라인은 프로덕션 환경에 필요한 핵심 개념과 아키텍처를 보여줍니다. 이를 기반으로 모든 과정에서 투명성과 설명 가능성을 유지하는 동시에 뉴스 기사를 모니터링하고, 엔티티 언급을 추적하며, 어떤 엔티티가 어떤 기사에 등장하는지에 대한 질문에 답하는 시스템을 구축할 수 있습니다.

HNSW에서 검색은 그래프 내의 후보 노드들을 반복적으로 확장하며, 현재까지 발견된 최근접 이웃의 제한된 집합을 유지하는 방식으로 진행됩니다. 각 확장 단계마다 비용(벡터 연산, 디스크 임의 탐색 등)이 발생하며, 검색이 진행될수록 그 비용 대비 얻게 되는 한계 이익은 점차 감소하는 경향이 있습니다.

HNSW 그래프 탐색을 최적화하는 한 가지 방법은, 새로운 진짜 이웃을 찾을 한계 확률이 더 이상 증가하지 않을 때 탐색을 중단하는 것입니다. 이러한 이유로, Elasticsearch 9.2에서는 새로운 조기 종료 메커니즘을 도입했습니다. 이 방식은 그래프 노드를 방문해도 새로운 최근접 이웃을 충분히 찾지 못하는 상태가 고정된 횟수만큼 연속으로 발생하면 검색 프로세스를 중단합니다.

이 글은 다양한 데이터 세트와 데이터 분포에 더 잘 대응할 수 있도록, HNSW의 조기 종료 메커니즘을 개선한 방법을 안내합니다.

HNSW의 조기 종료

HNSW에서 검색은 근접 그래프 내의 후보 노드들을 반복적으로 확장하며, 현재까지 발견된 근접 이웃의 제한된 집합을 유지하는 방식으로 진행됩니다. 이는 그래프 전체를 방문하거나 특정 조기 종료 기준을 충족할 때까지 계속됩니다.

따라서 조기 종료는 반드시 항상 최적화를 위한 선택 사항인 것만은 아닙니다. 검색 알고리즘 그 자체의 일부입니다. 탐색을 중단하기로 결정하는 그 순간이 효율성과 재현율 사이의 균형을 결정합니다. Elasticsearch에는 이미 HNSW 쿼리가 조기 종료될 수 있는 몇 가지 방법이 존재합니다.

• 방문하는 노드의 최대 개수는 정해져 있습니다.
• 정해진 제한 시간에 도달했습니다.

이러한 규칙들은 단순하고 예측 가능하지만, 검색이 실제로 어떻게 진행되고 있는지에 대해서는 대체로 무관심합니다. 또한, 이러한 규칙들은 주로 최종 사용자에게 적절한 시간 내에 쿼리가 완료되도록 하기 위한 용도로 사용됩니다.

이전 블로그 게시물에서 HNSW의 중복성이라는 개념을 소개한 바 있습니다. 요약하자면, HNSW가 새로운 최근접 이웃을 찾아내지 못하는 새로운 후보 노드들을 계속해서 평가할 때 중복 계산이 발생합니다.

인내심: 노력이 아닌 진척도를 측정하기

인내심이라는 개념은 조기 종료의 기준을 노력이 아닌 진전을 중심으로 재정의합니다.

다음과 같은 질문을 던지는 대신:

“우리가 몇 걸음을 걸었습니까?”

새로운 질문은 다음과 같습니다:

“더 나은 결과를 찾을 가망이 없다고 판단하기까지, 얼마만큼의 연산 낭비를 감수할 수 있을까요?"

HNSW 검색 과정에서, 초기 탐색은 일반적으로 top-k 후보 집단에 대해 가장 비약적인 개선을 만들어냅니다. HNSW 그래프 탐색의 첫 단계에서는, 알고리즘이 쿼리 벡터에 점점 더 가까운 이웃들을 계속해서 발견함에 따라 이웃 집합이 계속해서 업데이트됩니다. 시간이 흐름에 따라, 검색이 수렴하면서 이러한 개선은 점차 드물어집니다. 인내심 기반 종료는 이러한 패턴을 모니터링하며, 개선이 일정 기간 지속적으로 발생하지 않으면 검색을 종료합니다.

실제로 HNSW 그래프를 방문하는 동안, 후보 노드들을 거쳐 가며 큐 포화도를 함께 계산합니다. 이는 가장 최근의 그래프 노드를 방문하는 동안 변경되지 않고 그대로 남은 근접 이웃의 비율(또는 마지막 반복 과정에서 새로 추가된 이웃 수의 역수)을 측정합니다. 이러한 비율이 너무 많은 연속된 반복 과정 동안 과도하게 높아지면, 더 이상의 그래프 방문을 중단합니다

개념적으로 볼 때, 인내심은 HNSW 검색을 수익 체감의 과정으로 취급합니다. 수익이 정체되는 시점에 도달하면, 그래프를 계속해서 탐색하는 것은 실질적인 이익을 거의 주지 못합니다.

이러한 프레이밍은 강력합니다. 종료 시점을 임의로 정해진 고정된 한계치가 아니라, 관찰 가능한 결과에 직접 연결하기 때문입니다.

이러한 스마트 조기 종료 기술을 사용하면, 거의 완벽한 상대적 재현율을 유지하면서도 HNSW 그래프 탐색 과정에서 방문하는 노드 수를 줄일 수 있다는 장점이 있습니다.

이를 시각화하기 위해, 몇 가지 데이터 세트인 FinancialQA, Quora과 모델인 JinaV3, E5-small 조합을 대상으로 인내심 기반 조기 종료(et=static와 HNSW 기본 작동 방식(et=no)을 비교하여, 방문한 노드 수에 따른 재현율의 변화량을 그래프로 그려볼 수 있습니다.

정적 임계값 및 HNSW 동역학

실제로, Elasticsearch는 이를 정적 임계값을 사용하여 구현했습니다. 하나의 임계값은 포화 임계값입니다. 이는 우리가 차선이라고 간주하는 포화 비율을 의미합니다. 또 다른 임계값은 인내심 임계값입니다. 이는 큐 포화도가 여전히 낮은 상태임에도, 방문을 계속 허용할 연속적인 그래프 노드 방문 횟수를 의미합니다.

Elasticsearch 9.2에 이 조기 종료 전략을 도입할 당시, 지연 시간과 메모리 소모 측면에서 이득을 보면서도 재현율은 최대한 유지할 수 있도록 보수적인 기본값을 선택하기로 결정했습니다. 이러한 이유로, 포화 임계값을 100%로 설정하고, 인내심 임계값은 KNN 쿼리에서 num_candidates의 30% 수준(상한선 제한 있음)으로 설정했습니다.

많은 시나리오에서 이러한 설정들이 잘 작동하기도 했지만, 동일한 수의 이웃을 요청하는 두 쿼리라도 그 수렴 동작은 근본적으로 다를 수 있습니다. 어떤 쿼리는 밀집된 지역 이웃을 만나 빠르게 포화 상태에 도달하는 반면, 다른 쿼리는 경쟁력 있는 후보군을 찾기까지 길고 희소한 경로를 통과해야만 합니다. 후자가 효과적으로 처리하기 가장 어려운 것으로 나타났습니다.

그 결과, 때때로 다음과 같은 현상들이 관찰되었습니다:

• 쉬운 쿼리에 대한 과도한 탐색.
• 까다로운 쿼리에 대한 조기 종료.

따라서 고정된 임계값이 수렴에 대한 일괄적인 가정을 전제로 하는 반면, HNSW가 다양한 동역학에 더 잘 적응하도록 만들 수 있다는 점을 깨달았습니다.

HNSW 조기 종료 적응형 구현

적응형 조기 종료는 이 문제에 대해 기존과는 다른 각도에서 접근합니다. 미리 정의된 중단 임계값을 강제하는 대신, 알고리즘은 검색 역학 자체로부터 언제 멈춰야 할지를 추론합니다.

따라서 연속된 두 후보 사이의 큐 포화율을 비교하는 대신, 그래프 방문 중의 (웰포드 알고리즘을 사용한) 이동 평균 $\mu_{q,i}$ 및 표준 편차 $\sigma_{q,i}$와(과) 함께, 순간 평활 발견율 $d_{q,i}$(마지막 방문 i에서 쿼리 q에 대해 도입된 새로운 이웃의 수)를 도입하기로 결정했습니다. 발견율에 관한 이러한 통계치들은 각 쿼리당 개별적으로 계산됩니다. 이 정보를 사용하여 각 쿼리의 특성에 맞춰 서로 다른 수준의 인내심을 적용할 수 있습니다.

이전의 정적 임계값들은 이제 발견율 통계에 따라 적응형으로 변합니다. 포화 임계값은 이동 평균에 표준 편차를 더한 값이 되며, 인내심 수치는 표준 편차에 반비례하여 적응하고 확장되도록 만들었습니다.

조기 종료 규칙은 기존과 동일하게 유지됩니다. 즉, 순간 발견율이 적응형 포화 임계값보다 낮아질 때 포화가 발생합니다. 포화 상태가 적응형 인내심보다 더 많은 횟수의 연속적인 후보 방문 동안 지속되면, 그래프 방문이 중단됩니다

이러한 방식을 통해, KNN 쿼리의 num_candidates 매개변수(조기 종료 여부와 상관없이 항상 설정되어 있거나 기본값으로 남겨지는 값)에 의존하지 않으면서도, 각 쿼리와 벡터 분포에 맞춰 동적으로 더 잘 적응하는 동작을 구현할 수 있습니다.

FinancialQA 및 Quora에서 적응형 전략(et=adaptive)의 방문 노드당 재현율은 정적 전략(et=static) 및 기본 HNSW 동작(et=no)과 비교했을 때 더 높은 수치를 나타냅니다.

적응형 조기 종료는 Elasticsearch 9.3부터 HNSW 밀집 벡터 필드에 기본으로 활성화되며, 동일한 인덱스 수준 설정을 통해 나중에 비활성화할 수도 있습니다.

통합은 데이터 수집을 수행하도록 Filebeat 입력을 구성합니다. HTTP API에서 데이터를 수집하는 데 종종 HTTP JSON 입력이 사용되었습니다. 그러나 기본적인 목록 조회 API도 세부 사항에서 크게 차이가 날 수 있으며, HTTP JSON 입력의 YAML 기반 변환 모델에서는 필요한 수집 논리를 표현하는 것이 불편하거나 불가능한 경우가 있습니다.

공통 표현식 언어(CEL) 입력은 HTTP API와 보다 유연한 상호 작용을 촉진하기 위해 도입되었습니다. CEL은 빠르고 안전하며 확장 가능한 방식으로 조건과 데이터 변환을 표현해야 하는 애플리케이션에 내장되도록 설계된 언어입니다. 통합 빌더는 CEL 입력을 통해 설정을 읽고, 자체 상태를 추적하고, 요청을 생성하고, 응답을 처리하고, 궁극적으로 수집할 준비가 된 이벤트를 반환하는 하나의 표현식을 작성할 수 있습니다.

이 글에서는 CEL이 다른 프로그래밍 언어와 어떻게 다른지, CEL 입력을 위해 어떻게 확장되었는지, 또 데이터 수집 논리를 표현하는 데 어떤 유연성과 장점을 제공하는지 살펴보겠습니다.

CEL과 입력에서의 작동 원리

CEL은 표현식 언어입니다. 진술이 아닙니다. CEL을 작성할 때는 명령문으로 무엇을 할지 지시하는 것이 아니라, 표현식으로 어떤 값을 생성할지 정의합니다. 모든 CEL 표현식은 값을 생성하며, 더 작은 표현식을 결합하여 복잡한 규칙에 따른 결과를 만들어낼 수 있습니다. 다른 언어에서 명령문으로 작성되는 기능을 표현식으로 구현하는 방법을 나중에 살펴보겠습니다.

CEL은 의도적으로 튜링 완전 언어가 아닙니다. 무제한 루프를 허용하지 않습니다. 매크로를 사용하여 리스트와 맵을 처리하는 방법을 후에 살펴보겠지만, 무한 루프를 방지함으로써 개별 표현식에 대해 예측 가능하고 제한된 실행 시간을 보장합니다.

CEL 입력은 CEL 프로그램(표현식)과 몇 가지 초기 상태로 구성됩니다. 상태는 프로그램에 대한 입력으로 제공되고, 프로그램은 평가를 통해 출력 상태를 생성합니다. 출력 상태에 이벤트 목록이 포함되어 있으면 해당 이벤트가 제거되고 게시됩니다. 나머지 출력 상태는 다음 평가를 위한 입력으로 사용됩니다. 출력 상태에 하나 이상의 이벤트와 플래그 want_more: true가 포함되어 있으면 즉시 다음 평가가 수행되고, 포함되어 있지 않은 경우에는 구성된 시간 동안 대기한 후 진행됩니다. 다음은 입력의 제어 흐름을 간략하게 나타낸 다이어그램입니다.

각 평가의 출력은 입력이 실행되는 동안 다음 평가의 입력으로 전달됩니다. "cursor" 키 아래의 출력 데이터는 디스크에 보존되어 입력이 재시작된 후 다시 로드되지만, 나머지 상태는 재시작 시 보존되지 않습니다.

CEL 언어 자체는 기능이 제한적이며 부작용을 방지하지만, 확장 가능합니다. cel-go 구현은 선택적 구문 및 유형과 같은 기능을 추가합니다. Mito 라이브러리는 cel-go를 기반으로 빌드되어 HTTP 요청 기능을 포함한 더 많은 기능을 추가합니다. CEL 입력은 Mito의 CEL 버전을 사용합니다.

Mito와 함께 작동

CEL 입력을 사용하여 통합을 빌드하거나 디버깅할 때는 CEL 프로그램이 주어진 입력 상태에 대해 생성할 출력 상태를 이해하는 것이 가장 중요합니다. 개발 중에는 전체 Elastic 스택 환경에서 입력을 통해 CEL 프로그램을 실행하는 것이 번거로울 수 있습니다. Mito의 명령줄 도구를 사용하면 더 빠른 피드백 루프를 구현해 CEL 프로그램을 직접 실행하고 주어진 입력에 대한 출력 결과를 바로 확인할 수 있습니다.

Mito는 Go 언어로 작성되었으며 다음과 같이 설치할 수 있습니다.

go install github.com/elastic/mito/cmd/mito@latest

Mito로 CEL 프로그램을 실행할 때 일반적으로 두 개의 파일을 제공해야 합니다. 하나는 초기 입력 상태를 포함한 JSON 파일이고, 다른 하나는 CEL 프로그램의 소스 코드가 포함된 파일입니다.

mito -data state.json src.cel

쉽게 복사하여 붙여넣을 수 있도록 이 글의 예시는 각 파일의 내용을 <(echo '...content...') 로 감싸서 셸이 임시 파일을 즉시 생성하도록 하는 단일 명령으로 작성되었습니다. 자체 개발 시에는 실제 파일을 다루는 것이 더 쉬울 수 있습니다.

GitHub에서 이슈 데이터 가져오기

다음 예시에서는 GitHub API에서 이슈 데이터를 가져오는 전체 CEL 프로그램을 볼 수 있습니다. 초기 입력 상태에는 API 엔드포인트의 URL과 페이지네이션 처리 방식에 대한 정보가 포함되어 있습니다. CEL 프로그램은 입력 상태의 데이터를 사용하여 요청을 생성합니다. 응답을 디코딩하고, 그로부터 이벤트를 생성한 다음, 이를 출력 상태의 일부로 반환합니다.

mito -data <(echo '
  {
    "url": "https://api.github.com/repos/elastic/integrations/issues",
    "per_page": 3,
    "max_pages": 3
  }
') <(echo '
  int(state.?cursor.page.orValue(1)).as(page,
    (
      state.url + "?" + {
        "state": ["all"],
        "sort": ["created"],
        "direction": ["asc"],
        "per_page": [string(state.per_page)],
        "page": [string(page)],
      }.format_query()
    ).as(full_url,
      request("GET", full_url).with({
        "Header": {
          "Accept": ["application/vnd.github+json"],
          "X-GitHub-Api-Version": ["2022-11-28"],
        }
      }).do_request().as(resp,
        resp.Body.decode_json().as(data,
          state.with({
            "events": data.map(i, {
              "html_url": i.html_url,
              "title": i.title,
              "created_at": i.created_at,
            }),
            "cursor": { "page": page + 1 },
            "want_more": size(data) == state.per_page && page < state.max_pages,
          })
        )
      )
    )
  )
')

첫 번째 평가는 다음과 같은 출력을 생성합니다.

{
  "cursor": {
    "page": 2
  },
  "events": [
    {
      "created_at": "2018-09-14T09:47:35Z",
      "html_url": "https://github.com/elastic/integrations/issues/3250",
      "title": "Increase support of log formats in haproxy filebeat module"
    },
    {
      "created_at": "2019-02-06T12:37:37Z",
      "html_url": "https://github.com/elastic/integrations/issues/487",
      "title": "ETCD Metricbeat module needs polishing and grooming"
    },
    {
      "created_at": "2019-08-13T11:33:11Z",
      "html_url": "https://github.com/elastic/integrations/pull/1",
      "title": "Initial structure"
    }
  ],
  "max_pages": 3,
  "per_page": 3,
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "want_more": true
}

이벤트가 제거되고 CEL 입력에서 실행되면 수집을 위해 게시됩니다. 나머지 출력 결과는 다음 CEL 프로그램 평가의 입력 상태로 제공됩니다.

CEL 프로그램의 작동 방식을 이해하기 위해, 몇 가지 쉬운 CEL 예시시를 살펴보면서CEL 입력이 작동하는 방식에 대해 자세히 알아보겠습니다.

CEL 기본 사항

CEL 언어에는 문이 없고 표현식만 있습니다. 모든 성공적인 CEL 표현식은 최종 값으로 평가됩니다. 다음은 출력과 함께 작성할 수 있는 가장 간단한 CEL 표현식 중 하나입니다.

mito <(echo '
  "hello" + " " + "world"
')

"hello world"

간단한 표현식은 대개 직관적입니다. 수학적 연산은 같은 유형의 값(예시: int를 가진 int)에만 지원되므로 필요에 따라 (여기에서는int 에서 double로) 유형을 변환합니다.

mito <(echo '
  double((1 + 2) * (3 + 4)) / 2.0
')

10.5

CEL 언어에는 변수가 없지만, Mito의 as 매크로를 이용해 표현식에 이름을 부여하고 더 큰 표현식에서 사용할 수 있습니다. 이 예시에서 (1 + 1) 표현식은 2 값으로 평가되고 .as(n, ...)는 해당 값에 n 라는 이름을 부여하여 "one plus one is "+string(n) 표현식에서 사용합니다.

mito <(echo '
  (1 + 1).as(n, "one plus one is "+string(n))
')

"one plus one is 2"

또한 with 를 사용한 예처럼 맵에 정보를 축적하고 나중에 표현식에서 사용할 수도 있습니다.

mito <(echo '
  { "key": "value" }.with({ "key2": "value2" }).as(data,
    {
      "data": data,
      "size": size(data),
    }
  )
')

{
  "data": {
    "key": "value",
    "key2": "value2"
  },
  "size": 2
}

이 예시를 다시 살펴보세요. 중첩된 부분 ({ "data": data, "size": size(data), })은 최종 값의 형태를 제공합니다. "data" 및 "size" 키를 포함한 맵입니다. 이러한 키의 값은 표현식의 외부 부분에 정의된 data에 따라 달라집니다. CEL 표현식을 안쪽에서 바깥쪽으로 읽으면 반환되는 내용을 빠르게 파악하는 데 도움이 됩니다.

CEL에는 if와 같은 제어 흐름 문이 없지만, 삼항 연산자를 사용해 조건부 분기를 수행할 수 있습니다:

mito <(echo '
  1 + 1 < 12 ? "few" : "many"
')

"few"

CEL은 튜링 완전 언어가 아니기 때문에 무한 루프와 재귀가 지원되지 않습니다. 따라서 실행 시간을 예측할 수 있으며 , 이는 입력 데이터의 크기와 표현식의 복잡성에 비례합니다.

개별 CEL 표현식에서는 무한 루프가 불가능하지만, map 과 같은 매크로를 사용해 목록과 맵을 처리할 수 있습니다.

mito <(echo '
  [1, 2, 3].map(x, x * 2)
')

[2, 4, 6]

이 섹션에서는 다음과 같은 내용을 다룹니다.

• 스트링, 숫자, 리스트, 맵
• 스트링 연결
• 수학 연산
• 유형 캐스팅
• 조건문
• 하위 표현식의 이름 지정
• 컬렉션 처리

다음으로 HTTP 요청을 하는 방법을 살펴보겠습니다.

요청

Mito는 CEL을 확장해 HTTP 요청을 만드는 기능을 추가합니다.

mito <(echo '
  get("https://example.com").as(resp, string(resp.Body))
')

"..."

실행되기 전에 명시적으로 요청을 구성할 수 있습니다. 이를 통해 다양한 HTTP 메서드를 사용하고 헤더와 본문을 추가할 수 있습니다.

이 예시에서는 format_query의 도움을 받아 URL을 만들고, 요청에 헤더를 추가한 뒤, 응답 본문을 decode_json으로 구문 분석합니다. -log_requests 옵션이 주어지면 Mito는 각 요청 및 응답에 대한 자세한 정보를 JSON 형식으로 로그에 기록합니다.

mito -log_requests <(echo '
  request("GET",
    "https://postman-echo.com/get?" + {
        "q": ["query value"]
     }.format_query()
  ).with({
    "Header": { "Accept": ["application/json"] }
  }).do_request().as(resp, {
    "status": resp.StatusCode,
    "data": resp.Body.decode_json(),
  })
')

{"time":"...","level":"INFO","msg":"HTTP request",...}
{"time":"...","level":"INFO","msg":"HTTP response",...}
{
  "data": {
    "args": {
      "q": "query value"
    },
    "headers": {
      "accept": "application/json",
      "accept-encoding": "gzip, br",
      "host": "postman-echo.com",
      "user-agent": "Go-http-client/2.0",
      "x-forwarded-proto": "https"
    },
    "url": "https://postman-echo.com/get?q=query+value"
  },
  "status": 200
}

상태 관리 및 평가

이제 요청 방법과 원하는 출력 상태를 생성하는 데 필요한 CEL 기본 사항을 알아보았으니 출력 상태에 무엇을 넣어야 하는지, 그리고 이것이 이후 처리를 어떻게 지시하는지 자세히 살펴보겠습니다.

통합의 CEL 프로그램은 출력 상태가 다음 평가의 입력으로 적합하게 사용될 수 있도록 해야 합니다. 구성은 초기 상태를 설정하며, 적절한 변경이 있을 경우 출력에서 이를 반복해야 합니다. 이를 수행하는 쉬운 방법은 state.with({ ... }) 를 사용해 일부 재정의와 함께 상태 맵을 반복하는 것입니다. 작은 프로그램에서는 전체 프로그램을 state.with()로 감싸서 상태 전파가 출력 데이터를 생성하는 각 분기(예시: 성공, 오류)에서 반복되지 않도록 하는 패턴이 자주 사용됩니다.

상태 값이 초기 입력 상태에 하드코딩되지 않고 평가를 통해 초기화되는 경우, 프로그램은 초기값을 설정하기 전에 기존 값이 있는지 확인해야 합니다. 선택적 구문 및 유형에 대한 지원이 이러한 문제를 해결하는 데 도움이 될 수 있습니다. 맵 키에서 필드 이름 앞에 물음표를 사용하면 액세스가 선택 사항이 됩니다. 값으로 확인될 수도 있고 확인되지 않을 수도 있지만, 추가 선택적 액세스가 가능하며 값이 없는 경우 기본값을 쉽게 제공할 수 있습니다:

mito -data <(echo '{}') <(echo '
  int(state.?counter.orValue(0)).as(counter,
    state.with({
      "counter": counter + 1,
      "want_more": counter + 1 < 3,
    })
  )
')

{ "counter": 1, "want_more": true }
{ "counter": 2, "want_more": true }
{ "counter": 3, "want_more": false }

이 예시의 상태에서 읽은 카운터 값은 JSON과 JavaScript의 Number 유형이 정한 관례에 따라 부동소수점 숫자로 직렬화되어 있으므로 int로 캐스팅됩니다. 또한 여기서 "want_more": true는 Mito에 의해 존중되지만, CEL 입력에서 실행될 때는 출력에 이벤트가 포함될 때만 평가가 반복된다는 점에 유의해야 합니다.

CEL 입력으로 실행되는 CEL 프로그램의 경우 출력 맵에 "events" 키를 반환해야 합니다. 이 값은 이벤트 맵의 목록, 빈 목록 또는 단일 이벤트 맵일 수 있습니다. 단일 이벤트 사례는 일반적으로 오류 처리에 사용됩니다. 이벤트는 입력에 의해 게시되지만 해당 값도 로그에 기록되며, error.message 값이 설정되면 해당 값이 통합의 Fleet 상태를 업데이트하는 데 사용됩니다. 프로그램에서 오류가 아닌 단일 이벤트를 생성하는 경우 목록으로 래핑하는 것이 가장 좋습니다.

앞서 살펴본 GitHub 이슈 프로그램의 결과를 다시 한 번 살펴보세요.

{
  "url": "https://api.github.com/repos/elastic/integrations/issues",
  "per_page": 3,
  "max_pages": 3,
  "cursor": {
    "page": 2
  },
  "events": [
    { ... },
    { ... },
    { ... }
  ],
  "want_more": true
}

이 프로그램은 다음과 같은 방법으로 상태를 효과적으로 관리했습니다.

• url, per_page, max_pages에서 초기 상태 값을 반복합니다.
• cursor.page에서 재시작 후 지속되어야 할 상태를 추가합니다.
• events 목록에 게시할 준비가 된 이벤트를 반환합니다.
• want_more: true를 사용해 즉각적인 재평가를 요청합니다.

선택적 액세스 및 상태 관리, CEL 기본 사항 및 HTTP 요청에 대해 배워보았으니, 이제 전체 GitHub 이슈 프로그램을 읽을 수 있습니다. Mito로 실행하고 몇 가지 변경 사항을 실험해 보세요.

검토 및 리소스

이 글에서는 CEL 언어가 무엇인지, 그리고 Mito 라이브러리에서 CEL 입력에 사용하기 위해 어떻게 확장되었는지 알아봤습니다. GitHub API에서 이슈 정보를 가져오는 예제 프로그램에서 CEL의 유연성을 살펴보고, 초기 상태의 설정 액세스, HTTP API와의 상호작용, 수집할 이벤트 반환, 이후 프로그램 실행을 위한 상태 관리 등 해당 프로그램을 이해하는 데 필요한 모든 세부 사항을 살펴봤습니다.

CEL 입력을 사용하여 통합 기능을 구축하고 자세히 알아보려면 다음과 같은 여러 자료를 살펴보시기 바랍니다.

• CEL 입력 - Filebeat 설명서
• Mito 설명서
• 공통 표현식 언어 - cel.dev 웹사이트
• 통합 생성 - Elastic 문서

CEL 입력을 활용한 통합 구축에 있어 가장 유용한 리소스 중 하나는 GitHub에서 찾아볼 수 있는 기존 Elastic 통합의 CEL 코드입니다.

cel.yml.hbs Elastic 통합 리포지토리에 저장된 파일 - GitHub

1. Swift 업데이트 도착! 개발자들은 새로운 기능을 사용해 보고 싶어 합니다.
2. Swift 업데이트 도착! 새 앨범이 다음 달에 발매될 예정입니다.

이 추가 맥락을 통해 "Swift"라는 이름을 올바른 엔터티로 해석할 수 있습니다.

이전 게시물에서는 감시 목록을 설정하고 엔터티를 추가 맥락으로 보강했습니다. 위의 예시를 보면, 목록에 최소한 다음 두 개의 엔터티, "Taylor Swift"와 "Swift 프로그래밍 언어"가 있어야 합니다. 텍스트에서 엔터티 언급을 추출하는 방법도 다뤘습니다. 이 두 예시 모두 "Swift"를 추출합니다. 보강된 감시 목록과 추출된 엔터티라는 재료가 갖추어졌으니, 이제 주요 주제인 엔터티 매칭을 다룰 준비가 되었습니다.

유의 사항: 이것은 엔터티 매칭 개념을 교육하기 위해 설계된 교육용 프로토타입입니다. 프로덕션 시스템에서는 다양한 대규모 언어 모델(LLM), 사용자 지정 매칭 규칙, 특수 판단 파이프라인 또는 여러 매칭 전략을 결합한 앙상블 접근 방식을 사용할 수 있습니다.

문제: 매칭이 어려운 이유

인간의 언어는 놀라운 것입니다. 가장 흥미로운 속성 중 하나는 끝없는 창의성입니다. 우리는 무한하게 많은 수의 새로운 문장을 생성하고 이해할 수 있습니다. 그렇다면 엔터티 해석에서 정확한 일치가 드문 것이 과연 놀라운 일일까요? 작성자들은 가능한 한 창의적으로 되려고 노력합니다. 엔터티가 언급될 때마다 전체 이름을 쓰고 읽어야 한다면 매우 지루할 것입니다. 정확한 일치는 간편하지만, 실제로는 엔터티 해석을 위해 더 정교한 접근 방식이 필요합니다. 인간 작성자의 무한한 창의성을 최소한 어느 정도는 처리할 수 있을 만큼 강력한 접근 방식이 필요합니다. 그래서 우리는 문제를 두 단계로 분리합니다. Elasticsearch를 사용하여 가능성 있는 후보를 대규모로 검색하고, 그런 다음 LLM을 사용하여 이러한 후보가 실제로 동일한 실제 엔터티를 참조하는지 판단하는 것입니다.

해결책: 투명한 LLM 판단을 사용한 3단계 매칭

우리는 컴퓨터 사용 방식에서 패러다임 전환의 중심에 있습니다. 인터넷의 등장으로 로컬 컴퓨팅에서 글로벌 연결 네트워크로 전환된 것처럼, 생성형 AI는 콘텐츠, 코드 및 정보 생성 방식을 근본적으로 변화시키고 있습니다. 실제로, 이 시리즈에 포함된 교육용 프로토타입에서는 작성자의 세심한 프롬프트에 따라 거의 전적으로 LLM을 통한 "바이브 코딩" 방식을 사용했습니다. LLM이 인간 언어에 내재한 생산성에 도달했거나 도달할 것이라는 의미는 아니지만, 이제 엔터티 해석에 도움이 되는 강력한 리소스를 갖게 되었다는 것은 명백합니다.

생성형 AI에서 흔히 사용하는 패턴은 Retrieval-Augmented Generation(RAG)입니다. 여기서 검색(Retrieval)은 엔터티 후보를 검색하는 것(답변 생성이 아님)을 의미하며, LLM은 매칭 평가와 설명에만 엄격히 사용됩니다. LLM에 엔드 투 엔드 엔터티 해석을 요청할 수도 있지만, 시간과 비용 면에서 비용이 많이 듭니다. RAG는 LLM에 더 효율적으로 맥락을 제공하는 방식을 사용함으로써 LLM이 엔터티 해석을 효율적으로 지원하도록 돕습니다.

RAG의 검색 부분에서는 다시 Elasticsearch를 사용합니다. 먼저 정확한 매칭, 별칭 매칭, 그리고 키워드와 시맨틱 검색을 결합한 하이브리드 검색을 조합하여 잠재적 매칭을 찾습니다. 이 잠재적 매칭을 찾으면 LLM에 보내 판단을 받습니다. LLM은 최종 매칭 평가자 역할을 합니다. 또한 LLM은 그 추론을 설명하게 하는데, 이는 다른 엔터티 해석 시스템과의 중요한 차별점입니다. 이러한 설명이 없으면 엔터티 해석은 블랙박스와도 같습니다. 설명이 있어야 매칭이 타당한 이유를 알 수 있습니다.

핵심 개념: 3단계 매칭, 하이브리드 검색, 투명한 LLM 판단

3단계 매칭이란? 이 프로젝트의 시작 시점에 우리는 시맨틱 검색이 시스템의 중요한 부분이 될 것이라고 가정했지만, 모든 매칭이 그러한 정교한 검색을 요구하지는 않습니다. 일치하는 항목을 효율적으로 찾기 위해서, 문제에 대해 점진적인 접근 방식을 취합니다. 먼저 키워드 검색을 사용하여 정확히 일치하는 항목을 확인합니다. 정확히 일치하는 항목을 찾으면 작업이 완료되고 다음 단계로 넘어갈 수 있습니다. 정확히 일치하는 항목이 없으면, 별칭 매칭으로 전환합니다. 프로토타입에서는 간편함을 위해 별칭 매칭에서도 키워드를 사용한 정확한 일치 방식을 사용합니다. 프로덕션 환경에서는 이 단계를 정규화, 음역 규칙, 퍼지 매칭 또는 큐레이션된 별칭 테이블로 확장할 수 있습니다. 처음 두 단계에서 잠재적인 일치 항목을 찾지 못하면, Elasticsearch의 하이브리드 검색과 상호 순위 결합(RRF)을 통해 시맨틱 검색을 사용할 차례입니다.

하이브리드 검색이란? Elasticsearch에서는 시맨틱 검색을 사용하여 맥락을 고려한 의미 있는 일치 항목을 찾을 수 있습니다. Elasticsearch는 벡터 검색 및 하이브리드 검색에 널리 사용됩니다. 시맨틱 유사성은 의미 파악에 효과적이지만, 구조화된 필터링(예: 시간 범위, 위치 또는 식별자 기준)을 대체할 수 없으며 정확한 일치 항목이 있을 경우에는 불필요한 경우가 많습니다. Elasticsearch는 시맨틱 검색이 맞지 않는 작업에 뛰어난 어휘 검색으로 두각을 나타냈습니다. 두 접근법을 모두 활용하기 위해 단일 하이브리드 쿼리에서 어휘 검색과 시맨틱 검색을 사용합니다. 그런 다음 결과를 병합해서 RRF로 일치 가능성이 가장 높은 항목을 찾습니다. 프로토타입에서는 상위 두 결과가 LLM 판단을 위해 보낼 수 있는 잠재적 일치 항목이 됩니다.

LLM 판단이 필요한 이유? LLM의 판단과 설명을 통해 시스템은 모호성과 맥락을 투명하게 처리할 수 있습니다. 이는 맥락에 따라 여러 개체를 지칭할 수도 있는 "The President" 같은 사례에 매우 중요할 뿐 아니라, 별명이나 문화적 변형 같은 항목도 시스템에서 잘 작동하도록 해줍니다. 마지막으로, 제재 목록에서 엔터티를 식별할 때와 같이 중대한 작업을 고려할 때 시스템을 신뢰하기 위해서는 일치 항목이 수락된 이유를 알아야 합니다. 결정적으로, LLM은 전체 말뭉치를 검색하는 것이 아니라 Elasticsearch가 반환한 작은 후보 집합만 평가합니다.

실제 결과: LLM 추론을 사용한 매칭

자연어 처리 작업에서 가장 큰 과제 중 하나는 기대 결과를 알려주는 문서, 즉 "정답지"를 만드는 것입니다. 이것 없이는 작업에서 시스템의 성능을 판단하기가 거의 불가능하지만, 이러한 문서를 작성하는 과정은 어려울 수 있습니다. 엔터티 해석 프로토타입 개발을 위해, 테스트에 사용할 데이터를 설정하는 데 다시 한번 생성형 AI의 도움을 받았습니다.

먼저 별명과 음역법 같은 여러 과제 유형을 정의한 후, 시스템에 점차 더 커지고 어려워지는 티어형 데이터 세트 모음을 만들도록 LLM에 요청했습니다. 데이터 세트 생성은 기대만큼 간단하지 않았습니다. LLM은 정답을 너무 쉽게 찾도록 만들어서 "속임수"를 쓰는 경향이 강했습니다. 예를 들어, 과제 유형 중 하나는 의미론적 맥락에 초점을 맞췄습니다. 이 유형에는 "러시아 작가(Russian author)"를 "레프 톨스토이(Leo Tolstoy)"로 해석하는 것과 같은 것들이 포함되었습니다. LLM은 "러시아 작가(Russian author)"를 "레프 톨스토이(Leo Tolstoy)"의 별칭으로 잘못 표기했으며, 이로 인해 일치 항목을 찾기 위한 하이브리드 검색의 필요성이 없어졌습니다.

이와 같은 문제를 해결하기 위해 여러 차례 리팩토링을 거친 후, 5개의 데이터 세트 티어를 사용하게 되었습니다. 티어 1~4는 점점 더 커지고 더 많은 유형의 과제를 포함했습니다. 티어 5는 모든 과제 유형 중에서 가장 까다로운 예제들로 구성된 "궁극의 도전 과제" 데이터 세트였습니다. 모든 테스트 데이터는 종합 평가 디렉터리에서 확인할 수 있습니다.

프롬프트 기반 엔터티 해석 접근 방식을 평가하기 위해 티어 4 데이터 세트에 집중했습니다. 중요한 점은 이 평가가 통제된 실험으로 수행되어 엔터티 매칭 품질에 집중할 수 있었다는 것입니다. 감시 목록 데이터는 맥락 정보로 사전 보강되었으며, 엔터티는 문서에서 미리 추출되었습니다. 이를 통해 추출 정확도보다는 매칭에 초점을 맞춰 평가할 수 있었습니다. 이를 통해 매칭 품질에 집중합니다. 엔드 투 엔드 성능은 추가적으로 추출 재현율 및 보강 품질에 따라 달라질 수 있습니다.

평가 데이터 세트

티어 4 평가 데이터 세트는 시스템의 기능을 종합적으로 테스트합니다.[1]

• 감시 목록 엔터티: 다양한 유형의 엔터티 66개(사람, 조직, 위치).
• 테스트 문서: 실제 엔터티 해석 시나리오를 다룬 문서 69개.
• 예상 일치 항목: 모든 문서에서 예상 엔터티 일치 항목 206개.
• 과제 유형: 엔터티 해석의 다양한 측면을 테스트하는 과제 유형 15가지.

데이터 세트에 포함된 과제 유형은 다음과 같습니다.

• 별명: "Bob Smith" → "Robert Smith"(7개 문서).
• 직함 및 경칭: "Dr. Sarah Williams" → "Sarah Williams"(5개 문서).
• 의미론적 맥락: "Russian author" → "Leo Tolstoy"(8개 문서).
• 다국어 이름: 여러 스크립트로 이름 처리(6개 문서).
• 비즈니스 엔터티: 법인명 변형(7개 문서).
• 임원 참조: "Microsoft CEO" → "Satya Nadella"(5개 문서).
• 정치 지도자: 직함 기반 참조(5개 문서).
• 이니셜: "J. Smith" → "John Smith"(3개 문서).
• 이름 순서 변형: 다양한 이름 순서 규칙(3개 문서).
• 잘린 이름: 부분 이름 일치(3개 문서).
• 이름 분할: 텍스트에 걸쳐 이름 분할(3개 문서).
• 누락된 공백/하이픈: 서식 변형(2개 문서).
• 음역: 교차 스크립트 이름 매칭(2개 문서).
• 결합된 과제: 하나의 문서에 여러 과제(6개 문서).
• 복잡한 비즈니스: 계층적 비즈니스 관계(5개 문서).

프롬프트 기반 엔터티 해석이 어떻게 수행되었는지 살펴보겠습니다.

전반적인 성능

결과는 LLM 기반 매치 평가에 많은 가능성이 있음을 보여주지만, 동시에 심각한 신뢰성 문제도 드러났습니다. 각 후보 쌍은 LLM에 의해 평가되어야 하므로, 검색이 잘 작동하더라도 구조화된 출력에 오류가 있으면 허용률과 재현율을 억제할 수 있습니다.

오류율 문제

앞에서 설명한 대로, 프로토타입에서 가장 먼저 한 일은 Elasticsearch를 사용하여 잠재적인 일치 쌍을 생성하는 것입니다. 이러한 잠재적 일치 항목 각각은 LLM에 의해 평가되어야 합니다. 모든 일치 항목을 효율적으로 처리하기 위해 LLM 호출을 배치 처리합니다. 이렇게 하면 API 비용과 지연 시간이 줄어들지만, 출력에 잘못된 형식의 JSON이 포함될 위험도 높아집니다. 배치 크기가 증가함에 따라 JSON은 더 길고 복잡해지므로 LLM이 유효하지 않은 JSON을 생성할 가능성이 높아집니다. 여기에서 30% 오류율이 발생합니다. 평가에서는 요청당 5개의 일치 항목을 배치 크기로 사용했습니다. 이처럼 보수적인 배치 크기를 사용했음에도 불구하고 여전히 JSON 구문 분석 오류가 발생하여 평가 결과가 크게 왜곡됩니다.

다음 단계: LLM 통합 최적화

이제 시맨틱 검색과 LLM 판단을 사용하여 엔터티를 매칭했으므로 완전한 엔터티 해석 파이프라인을 갖추게 되었습니다. 하지만 이 접근 방식은 모델의 판단은 정확하지만 출력 결과가 사용 불가능할 때 새로운 오류 모드를 불러옵니다. 안정성과 비용 효율성을 높이기 위해 LLM 통합을 최적화할 수 있습니다. 다음 게시물에서는 구조화된 출력을 위해 함수 호출을 사용하는 방법을 탐구할 것입니다. 이는 구조와 유형 안전성을 보장하면서 오류와 비용을 줄여줍니다.

직접 사용해 보기

엔터티 매칭을 직접 확인해 보고 싶으신가요? 실제 구현, 자세한 설명 및 실제 예제가 포함된 엔터티 매칭 노트북을 확인해 보세요. 이 노트북은 3단계 검색, RRF를 사용한 하이브리드 검색, 그리고 추론을 포함한 LLM 기반 판단을 통해 엔터티를 매칭하는 방법을 정확하게 보여줍니다.

유의 사항: 이것은 개념을 교육하기 위해 설계된 교육용 프로토타입입니다. 프로덕션 시스템을 구축할 때는 이 학습 중심 프로토타입에서 다루지 않는 모델 선택, 비용 최적화, 지연 시간 요구 사항, 품질 검증, 오류 처리 및 모니터링과 같은 추가 요소를 고려하세요.

참고

1. 이 데이터 세트는 교육용으로 설계된 합성 데이터 세트입니다. 실제 문제를 어느 정도 반영하지만 특정 프로덕션 환경을 대표하는 것은 아닙니다.

문서 코퍼스 2,000만 개에 대한 벤치마크에서 Elasticsearch는 필터링된 벡터 검색에서 OpenSearch 대비 최대 8배 높은 처리량을 제공하는 동시에, 테스트한 모든 구성에서 더 높은 Recall@100을 달성했습니다. 컨텍스트 엔지니어링에는 빠른 벡터 검색 이상이 필요합니다. 워크플로우가 반복되면서 하이브리드 검색 및 필터링과 같은 강력한 관련성 제어, 운영 간소화, 예측 가능한 성능이 필요합니다. 그러나 에이전트가 요청당 검색, 추론, 검색 루프를 여러 번 실행하는 경우가 많기 때문에 검색 지연 시간이 배가되므로, 이 문제를 개선하면 엔드투엔드 응답성 향상과 비용 절감 효과를 누릴 수 있습니다.

컨텍스트 엔지니어링에서 검색은 일회성 단계가 아닙니다. 에이전트와 애플리케이션은 검색 → 추론 → 검색과 같은 루프를 반복적으로 실행해 쿼리를 정제하고, 사실을 검증하며, 근거 있는 컨텍스트를 조립하고, 작업을 완료합니다. 이 패턴은 에이전트 워크플로우와 반복 Retrieval-Augmented Generation(RAG)에서 흔히 볼 수 있습니다. 사용자 요청당 검색이 여러 번 호출될 수 있으므로 응답 시간이 지연되거나 인프라 비용이 증가할 수 있습니다.

벡터 검색 성능이 중요한 이유

쇼핑 어시스턴트가 '15인치 노트북이 들어가고, 방수 기능이 있으며, 금요일까지 배송 가능한 6만원 이하의 기내용 백팩을 찾는다'는 질문에 답하는 경우를 생각해 보겠습니다.

실제 환경에서 어시스턴트가 벡터 쿼리를 한 번만 실행하고 멈추는 경우가 거의 없습니다. 올바른 컨텍스트를 구축하기 위해 검색 루프를 실행하는데, 각 단계는 일반적으로 가용성, 지역, 배송 예정일, 브랜드 규칙 및 정책 적합성과 같은 필터에 의해 제한을 받습니다.

1단계: 의도를 해석해 제약 조건으로 변환

에이전트는 요청을 다음과 같은 구조화된 필터와 의미론적 쿼리로 변환합니다.

• 필터: 재고 있음, 사용자의 우편번호로 배송 가능, 금요일까지 배송, 가격 6만원 미만, 유효한 상품 목록
• 벡터 쿼리: '기내 반입 가능한 백팩, 15인치 노트북, 방수'

2단계: 후보를 검색한 후 정제

우수한 일치 항목을 놓치지 않기 위해 종종 변형된 검색을 반복합니다.

• '노트북 슬리브가 포함된 기내용 백팩'
• '통근용 방수 백팩 15인치'
• '기내용 경량 백팩'

관련성이 없거나 사용할 수 없는 항목을 검색하는 것은 컨텍스트 낭비이므로 각 쿼리는 동일한 자격 필터를 사용합니다.

3단계: 위험을 줄이기 위해 확장하여 세부 정보 확인

그런 다음 에이전트는 최종 답변에 영향을 미치는 주요 속성을 확인하기 위해 데이터를 다시 검색합니다.

• 재질 및 방수 기능 관련 문구
• 치수 및 노트북 수납 공간 크기
• 반품 정책 또는 보증 제약 조건
• 재고가 부족한 경우 대체 옵션

이것이 검색, 추론, 검색, 조립을 거치는 다단계 컨텍스트 엔지니어링입니다.

컨텍스트 엔지니어링에서 지연 시간과 재현율이 중요한 이유

이러한 상호작용은 사용자 세션당 수십 건의 필터링된 검색 호출을 포함할 수 있습니다. 따라서 통화당 지연 시간이 엔드투엔드 응답 시간에 직접적인 영향을 미치며, 재현율이 낮으면 에이전트가 추가 재시도를 하거나 적격 항목을 놓치게 되어 응답 품질이 저하됩니다.

요점: 컨텍스트 엔지니어링 시스템에서 필터링된 근사 이웃(ANN)은 일회성 조회로 끝나지 않습니다. 이는 제약 조건 하에서 반복되는 작업이므로, 대형 언어 모델(LLM)이 가장 중요한 구성 요소인 경우에도 벡터 검색 성능이 지연 시간, 처리량, 비용에 즉각적으로 영향을 미칩니다.

벤치마킹

결과

그래프 2에서 각 점은 하나의 테스트 구성을 나타냅니다. 지연 시간이 짧고 재현율이 높은 최상의 결과는 왼쪽 상단에 표시됩니다. Elasticsearch의 결과가 OpenSearch보다 지속적으로 왼쪽 상단에 가깝게 위치한다는 점에서 동일한 워크로드 설정에서 더 나은 속도와 정확도를 확인할 수 있습니다.

주요 인사이트

• s_n_r_value: size_numCandidates_rescoreOversample 의 약어(k 및 numCandidates는 이러한 테스트에서 numCandidates와 동일하게 설정됨), 예를 들어 100_500_1 은 size=100, numCandidates=500 및 k=500, rescore oversample=1을 의미합니다.
• 재현율: 해당 구성에 대한 측정된 Recall@100
• 평균 지연 시간(ms): 쿼리당 평균 엔드투엔드 지연 시간
• 처리량: 초당 쿼리 수
• 재현율 %: Elasticsearch와 OpenSearch의 상대적 재현율 상승(Elasticsearch-OpenSearch)/OpenSearch
• 지연 시간 Xs: OpenSearch의 평균 지연 시간을 Elasticsearch의 평균 지연 시간으로 나눈 값
• 처리량 Xs: Elasticsearch 처리량을 OpenSearch 처리량으로 나눈 값

예를 들어, 100_9000_1에서 OpenSearch는 검색당 평균 687밀리초를 기록하는 반면, Elasticsearch에서는 90밀리초이며, 10단계 검색 루프에서는 약 10x(687-90)=6초의 추가 대기 시간이 발생합니다.

전체 결과 보기.

방법론

Python을 사용하여 쿼리를 전송하고 응답 시간 및 기타 통계를 추적하기 위해 다음 쿼리를 각 엔진에 전송했습니다. 벡터 검색 엔진의 성능은 고려할 후보 수, 재채점의 적극성, 반환할 컨텍스트의 양 등 핵심 매개변수를 어떻게 조정하느냐에 따라 달라진다는 점을 유의하시기 바랍니다. 이러한 설정은 재현율(올바른 답변을 찾을 가능성)과 대기 시간(결과를 얻는 속도)에 직접적인 영향을 미칩니다.

벤치마크 테스트에서는 에이전틱 검색 루프에서 일반적으로 조정하는 것과 동일한 후보, 재채점, 결과 크기 설정을 사용하여 해당 워크로드에서 Elasticsearch의 성능을 측정했습니다. 그런 다음 참조를 위해 동일한 설정으로 OpenSearch를 실행했습니다.

OpenSearch

GET /_search
{
  "query": {
    "knn": {
      "": {
        "vector": [...],
        "k": ,
        "method_parameters": {
          "ef_search": 
        },
        "rescore": {
          "oversample_factor": 
        },
        "filter": {
          
        }
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: 클라이언트에 반환된 결과 수입니다. 이 벤치마크에서는 Recall@100을 계산하기 위해 결과 크기가 100입니다.
• "k": <NUMBER_OF_CANDIDATES>: 최근접 이웃 후보의 수입니다.
• "ef_search": <NUMBER_OF_CANDIDATES>: 검사할 벡터의 개수.
• "oversample_factor": <OVERSAMPLE>: 재채점 전에 검색되는 후보 벡터의 수입니다.

Elasticsearch

GET /_search
{
  "query": {
    "knn": {
      "field": "",
      "query_vector": [...],
      "k": ,
      "num_candidates": ,
      "rescore_vector": {
        "oversample": 
      },
      "filter": {
        
      }
    }
  },
  "size": ,
  "_source": {
    "excludes": [
      ""
    ]
  }
}

• "size": <RESULT_SIZE>: 클라이언트에 반환된 결과 수입니다. 이 벤치마크에서는 Recall@100을 계산하기 위해 결과 크기가 100입니다.
• "k": <NUMBER_OF_CANDIDATES>각 샤드에서 반환할 가장 가까운 이웃의 수입니다.
• "num_candidates": <NUMBER_OF_CANDIDATES>: knn 검색 수행 시 샤드별로 고려할 최근접 이웃 후보 수.
• "oversample": <OVERSAMPLE>: 재채점 전에 검색되는 후보 벡터의 수입니다.

예

Knn 쿼리(100_500_1)는 다음과 같습니다.

OpenSearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "search_catalog_embedding": {
        "vector": [...],
        "k": 500,
        "method_parameters": {
          "ef_search": 500
        },
        "rescore": {
          "oversample_factor": 1
        },
        "filter": {
          "term": {
            "valid": true
          }
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

Elasticsearch

GET search_catalog_128/_search
{
  "query": {
    "knn": {
      "field": "search_catalog_embedding",
      "query_vector": [...],
      "k": 500,
      "num_candidates": 500,
      "rescore_vector": {
        "oversample": 1
      },
      "filter": {
        "term": {
          "valid": true
        }
      }
    }
  },
  "size": 100,
  "_source": {
    "excludes": [
      "search_catalog_embedding"
    ]
  }
}

전체 구성, Terraform 스크립트, Kubernetes 매니페스트 및 벤치마킹 코드는 이 저장소의 es-9.3-vs-os-3.5-vector-search 폴더에서 확인할 수 있습니다.

클러스터 설정

테스트는 각각 16개의 vCPU와 64GB RAM을 갖춘 6개의 e2-standard-16 클라우드 서버에서 실행되었습니다. 각 서버에서 검색 엔진 노드를 실행하는 각 Kubernetes 포드에 15개의 vCPU와 56GB RAM을 할당하였으며, 그 중 28GB는 JVM 힙을 위해 예약했습니다.

클러스터는 Elasticsearch 9.3.0과 OpenSearch 3.5.0 (Lucene 10.3.2)을 실행합니다. 이 벤치마크에서 두 시스템 모두 동일한 Lucene 버전을 사용하기 때문에, 관찰된 처리량과 지연 시간 차이는 Lucene에만 기인하는 것이 아니라 각 엔진이 필터링된 kNN(k-최근 이웃) 검색 및 재채점을 통합하고 실행하는 방식의 차이를 반영합니다. 3개의 기본 샤드와 1개의 복제본이 있는 단일 인덱스를 사용했습니다(따라서 노드당 1개씩 총 6개의 샤드).

또한 같은 지역 내 별도의 서버를 사용해 벤치마크 클라이언트를 실행하고 타이밍 통계를 수집했습니다.

데이터 세트

이 벤치마크에서는 대규모 실제 환경에서의 필터링된 벡터 검색을 반영하도록 설계된 대규모 이커머스 스타일의 카탈로그 임베딩 데이터 세트(2,000만 개 문서)을 사용했습니다.

각 문서는 카탈로그 항목을 나타내며 다음을 포함합니다.

• 128차원 고밀도 벡터 임베딩으로, 대략적인 kNN 검색에 사용됩니다.
• 필터링에 사용되는 구조화된 메타데이터 필드(예: 항목 유효성 및 가용성, 기타 카탈로그 제약 조건)는 적합한 하위 집합 내에서만 가장 가까운 이웃을 검색하는 일반적인 제작 패턴을 지원합니다.

이 데이터 세트를 선택한 이유는 선택한 이유는 프로덕션 환경의 에이전틱 및 RAG 스타일 시스템에서 나타나는 핵심 성능 과제를 잘 반영하기 때문입니다. 벡터 유사도만으로는 충분하지 않고, 검색은 필터에 의해 제한을 받는 경우가 많고, 시스템은 해당 제약 조건 하에서 지연 시간을 낮게 유지하면서 높은 재현율을 달성해야 합니다. 소규모 QA 스타일 데이터 세트와 비교했을 때, 2,000만 개 문서 코퍼스는 실제 환경에서 필터링된 ANN 시스템이 직면하는 규모와 후보 압력을 더 잘 반영합니다.

결론

현대 AI 아키텍처, 특히 컨텍스트 엔지니어링을 중심으로 구축된 아키텍처에서 벡터 검색 속도는 사소한 구현 세부 사항으로 치부할 수 없습니다. 이는 효과를 배가시킵니다. 에이전트와 워크플로가 검색 → 추론 → 검색 과정을 반복할 때, 검색 성능은 엔드투엔드 지연 시간, 처리량, 모델에 입력되는 컨텍스트 품질에 직접적인 영향을 미칩니다.

벤치마크 테스트 결과, Elasticsearch는 정확한 문서 검색 여부가 중요한 시나리오(단순히 유사한 벡터를 검색하는 것이 아닌)에서 OpenSearch보다 지속적으로 더 높은 재현율과 더 낮은 지연 시간을 제공했습니다. 제어된 데이터 세트에서 차이는 분명하며, 실제 환경에서는 대규모 검색 호출 전반에 걸쳐 이러한 이점이 누적되어 응답성을 향상시키고, 용량 여유를 확대하며, 인프라 비용을 절감합니다.

추가 읽기

1. 컨텍스트 엔지니어링이란 무엇인가요?
2. 하이브리드 검색 및 컨텍스트 엔지니어링의 발전
3. AI 에이전트를 위한 컨텍스트 엔지니어링에서 관련성의 영향

이 제품군에는 두 가지 모델이 포함되어 있습니다:

• jina-embeddings-v5-text-small
• jina-embeddings-v5-text-nano

이러한 모델은 임베딩 모델을 위한 혁신적인 새로운 훈련 방식의 성공적인 결과입니다. 두 모델 모두 크기가 몇 배나 큰 모델보다 성능이 뛰어나 메모리와 컴퓨팅 리소스를 절약하고 요청에 더 빠르게 응답합니다.

jina-embeddings-v5-text-small 모델은 6억 7,700만개의 매개변수를 가지고 있으며, 32,768개의 토큰 입력 컨텍스트 창을 지원하고 기본적으로 1,024차원 임베딩을 생성합니다.

jina-embeddings-v5-text-nano 무게는 형제 제품의 크기의 대략 3분의 1로, 2억 3,900만 개의 매개변수와 8,192개의 토큰의 입력 컨텍스트 창을 가지며, 768차원의 간결한 임베딩을 제공합니다.

이 두 모델은 전체 MMTEB(다국어 MTEB) 벤치마크 성능에서 동급 최고 수준입니다. 5억 개 미만의 매개변수를 가진 모델 중, jina-embeddings-v5-text-nano는 2억 5,000만 개 미만의 매개변수를 가지고 있음에도 불구하고 최고 성능을 보이며, jina-embeddings-v5-text-small 모델은 7억 5,000만 개 미만의 매개변수를 가진 다국어 임베딩 모델 중 선두에 있습니다.

이러한 모델은 Elastic Inference Service(EIS), 온라인 API를 통해 사용할 수 있으며 로컬 호스팅도 가능합니다. jina-embeddings-v5-text 모델에 액세스하는 방법에 대한 지침은 아래의 '시작하기' 섹션을 참조하세요.

임베딩 모델과 의미 색인화는 검색 알고리즘의 정확도를 획기적으로 향상시킬 뿐만 아니라 의미 유사성 및 의미 추출과 관련된 다양한 작업에도 활용될 수 있습니다. 예를 들면 다음과 같습니다.

• 중복된 텍스트 찾기.
• 의역 및 번역 인식하기.
• 주제 발견.
• 추천 엔진.
• 감정 및 의도 분석.
• 스팸 필터링.
• 그 밖에도 여러 가지가 있습니다.

기능

이 새로운 모델 제품군은 관련성을 높이고 비용을 절감하도록 설계된 여러 기능을 갖추고 있습니다.

작업 최적화

jina-embeddings-v5-text 모델을 네 가지 작업 유형에 맞게 최적화했습니다.

한 작업에 최적화하는 것은 일반적으로 다른 작업에서 타협을 의미하므로 대부분의 임베딩 모델은 한 종류의 작업에 대해서만 경쟁력 있는 성능을 가집니다. 하지만 jina-embeddings-v5-text 모델은 작업별 로우랭크 적응(LoRA) 어댑터를 훈련하여 타협 없이 네 가지 영역 모두에 전문성을 갖출 수 있습니다.

LoRA 어댑터는 AI 모델의 동작을 극적으로 변화시키면서도 전체 크기는 약간만 늘리는 일종의 플러그인입니다. 각 작업마다 수억 개의 매개변수가 있는 전체 모델을 사용하는 대신 jina-embeddings-v5-text 모델 제품군을 사용하면 각 작업마다 컴팩트한 LoRA 어댑터가 포함된 하나의 모델만 사용할 수 있습니다. 이렇게 하면 메모리, 저장 공간, 추론 비용을 절약할 수 있습니다.

임베딩 잘라내기

최소한의 비용으로 임베딩의 품질을 유지하면서 더 작은 크기로 줄일 수 있는 Matryoshka 표현 학습을 사용하여 jina-embeddings-v5-text 모델을 훈련시켰습니다.

기본적으로 jina-embeddings-v5-text-small은 1024차원 임베딩 벡터를 생성하며, 각 벡터는 16비트 숫자로 표현되어 각 임베딩 크기가 2KB입니다. 대규모 문서 컬렉션의 경우 저장해야 할 데이터가 많을 수 있으며, 임베딩으로 가득 찬 벡터 데이터베이스에서 검색하는 것은 데이터베이스의 크기와 저장된 각 벡터의 차원 수 모두에 비례합니다.

하지만 임베딩의 크기를 절반으로 줄이면(1024차원 중 512차원을 버리면) 공간을 절반으로 줄이면서 검색 속도를 두 배로 높일 수 있습니다. 이는 성능에 영향을 미칩니다. 정보를 버리면 정밀도가 떨어집니다. 그러나 아래의 그래프가 보여주듯이, 임베딩의 절반을 제거하더라도 성능은 약간만 저하됩니다.

임베딩이 최소 256차원을 가지는 한, 정밀도 손실은 상당히 작게 유지되어야 합니다. 그러나 이 수준 이하에서는 관련성과 정확도가 빠르게 저하됩니다.

이처럼 임베딩을 잘라내는 방식을 통해 사용자는 정확도와 컴퓨팅 비용 간의 균형을 스스로 관리할 수 있습니다. 이 솔루션은 검색 AI를 통해 효율성을 크게 향상시키고 비용을 대폭 절감할 수 있는 도구를 제공합니다.

강력한 양자화

양자화는 임베딩의 크기를 줄이는 또 다른 방법입니다. 양자화는 각 임베딩의 일부를 버리는 대신 임베딩에 포함된 숫자의 정밀도를 낮춥니다. jina-embeddings-v5-text 모델은 16비트 숫자로 임베딩을 생성하지만, 이 숫자를 반올림하여 정밀도와 저장에 필요한 비트 수를 줄일 수 있습니다. 가장 극단적인 경우, 각 숫자를 1비트(0 또는 1)로 줄여 jina-embeddings-v5-text의 기본 1024차원 임베딩을 2킬로바이트에서 128바이트로 압축할 수 있으며, 이는 이진 양자화만으로 94% 줄어든 것입니다. 잘라내기와 마찬가지로 메모리 및 컴퓨팅 비용을 크게 절감할 수 있습니다. 하지만 잘라내기와 마찬가지로 양자화는 임베딩의 정확도를 떨어뜨립니다.

정확도 손실을 최소화하여 Elasticsearch의 더 나은 이진 양자화(BBQ) 기능을 사용하도록 jina-embeddings-v5-text 모델을 훈련시켰으며, 이러한 모델의 이진화된 임베딩에 대한 벤치마크 테스트 결과 이진화되지 않은 임베딩과 거의 동일한 성능을 보여주었습니다. 이진화 성능에 대한 자세한 제거 연구는 기술 보고서를 참조하세요.

다국어 성능

많은 임베딩 모델은 다양한 언어가 포함된 자료에 대한 훈련을 거쳤기 때문에 다국어를 지원합니다. 하지만 그렇다고 해서 모든 지원 언어에서 모두 똑같이 잘 작동하는 것은 아닙니다.

MMTEB 다국어 벤치마크에서 211개 언어를 식별하고 이를 분리하여 언어별로 유사한 모델과 비교할 수 있도록 했습니다. 아래 이미지는 히트맵 형태로 결과를 요약한 것입니다. 각 패치는 언어(ISO-639 코드로 식별)이며, 초록색이 짙을수록 유사한 모델의 평균에 비해 더 나은 성능을 발휘하는 모델입니다.

언어마다 정확도는 다르지만 jina-embeddings-v5-text 모델은 전 세계 대부분의 언어에서 최첨단 또는 그에 가까운 정확도를 제공합니다.

다국어 성능에 대한 자세한 내용은 jina-embeddings-v5-text 기술 보고서를 참조하세요.

Elastic의 Jina: 검색을 위한 최첨단 네이티브 AI

EIS의 jina-embeddings-v5-text 모델을 사용하면 프로비저닝이나 확장을 위한 인프라 없이 완전 관리형 GPU 가속 추론을 통해 고성능 다국어 임베딩 모델을 Elasticsearch에서 기본적으로 실행할 수 있습니다. jina-embeddings-v5-text 모델은 최신 AI 개발로 구동되는 컴팩트한 다국어 모델로 성장하는 EIS 모델 카탈로그를 확장합니다. 이러한 모델은 정보 검색 및 표준 데이터 분석 벤치마크에서 최첨단 성능을 제공하며, 비교할 수 없는 전 세계적인 다국어 지원을 제공합니다.

크기가 크게 다른 두 가지 모델이 있으므로 사용자는 용도와 예산에 가장 적합한 모델을 선택할 수 있습니다. 또한, 더 작은 크기로 잘라내거나 더 낮은 정밀도로 정량화해도 성능이 유지되는 강력한 임베딩을 통해 jina-embeddings-v5-text 모델은 저장 공간 및 컴퓨팅 비용, 처리 지연 시간을 더욱 구체적으로 절감할 수 있는 기회를 제공합니다.

jina-embeddings-v5-text 제품군, Jina Reranker, Elastic의 빠른 벡터 및 BM25 검색을 통해 사용자는 이제 Elastic의 엔드투엔드 최신 하이브리드 검색에 액세스할 수 있습니다. Retrieval-Augmented Generation(RAG) 파이프라인, 검색 애플리케이션, 데이터 분석 등 가장 연관성이 높은 결과가 필요한 경우, Jina 검색 AI 모델이 포함된 Elastic은 견고하고 비용 효율적인 품질을 제공합니다.

시작하기

jina-embeddings-v5-text 모델은 EIS에 완전히 통합되어 있으며, 색인 생성 시 type 필드를 semantic_text로 설정하고 inference_id 필드에 모델(jina-embeddings-v5-text-small 또는 jina-embeddings-v5-text-nano)을 지정하면 이 예시에서와 같이 사용할 수 있습니다.

PUT multilingual-semantic-index
{
  "mappings": {
    "properties": {
      "content": {
        "type": "semantic_text",
        "inference_id": ".jina-embeddings-v5-text-small"
      }
    }
  }
}

# Ingest data about France
POST multilingual-semantic-index/_doc
{
  "content": "The capital of France is Paris"}

GET multilingual-semantic-index/_search
{
  "query": {
    "semantic": {
      "field": "content",
      "query": "What is the French capital?"
    }
  }
}

Elasticsearch는 색인 및 검색 과정에서 적절한 LoRA 어댑터를 자동으로 선택합니다. 임베딩 차원(위의 "임베딩 잘라내기" 섹션 참조)은 사용자 지정 추론 엔드포인트를 생성할 때 설정할 수 있습니다.

jina-embeddings-v5-text 모델 사용에 관한 자세한 내용은 Elasticsearch 문서를 참조하세요.

추가 정보

jina-embeddings-v5-text 모델에 대한 자세한 내용은 Jina AI 블로그의 릴리즈 노트와 기술 보고서를 참조하세요. 성능 및 Jina AI의 혁신적인 새로운 훈련 절차에 대한 자세한 기술 정보를 확인할 수 있습니다. 이러한 모델을 로컬에서 다운로드하고 실행하는 방법에 대한 자세한 내용은 Hugging Face의 jina-embeddings-v5-text 컬렉션 페이지를 참조하세요.

Jina AI 모델은 CC-BY-NC-4.0 라이선스 하에 제공되므로 무료로 다운로드하여 사용할 수 있으나, 상업적 사용은 Elastic 영업팀에 문의해 주시기 바랍니다.

이 글에서는 최소 점수 매개변수를 사용하여 시맨틱 검색 결과의 정밀도를 높이는 방법을 알아봅니다. 이 블로그 게시물에 제공된 예시를 테스트해 보고 싶다면 관련 Jupyter 노트북으로 이동하세요.

배경: 정밀도와 재현율

검색 정확도에서 정밀도와 재현율은 핵심 개념입니다. 아직 익숙하지 않은 독자라면 관련 내용을 알아보기를 강력히 권장합니다. 다음은 간략한 내용입니다.

• 정밀도: 사용자와 관련된 반환된 검색 결과의 비율.
• 재현율: 검색 결과 집합에 포함된 코퍼스 내 모든 관련 문서의 비율.

다시 말해 정밀도는 오직 관련성 있는 결과만 반환하는 것이고, 재현율은 관련성 있는 모든 결과를 반환하는 것입니다. 짐작하시겠지만, 이 두 가지는 종종 상충되는 요구 사항입니다. 시맨틱 검색은 재현율은 매우 높지만, 정밀도는 떨어지는 경향이 있습니다. 이 속성을 해결하는 방법을 알아보려면 계속 읽어보세요.

최소 점수 매개변수 소개

'min_score' 매개변수를 사용하면 최소 점수를 설정하여 정밀도를 향상할 수 있으며, 이 매개변수는 정의된 임계값보다 낮은 점수를 가진 일치 항목을 제거하여 결과 집합을 잘라냅니다. 다음은 간단한 예시입니다.

GET search-movies/_search
{
  "retriever": {
    "linear": {
      "min_score": 4,
      "retrievers": [
        ...
      ]
    }
  }
}

점수 정규화

최소 점수를 설정하는 것도 좋지만, 모든 시맨틱 모델이 정적 임계값에 적합한 점수를 반환하는 것은 아닙니다. 예를 들어 ELSER는 제한이 없는 점수를 반환합니다. 일부 밀집 모델 점수는 밀집도가 높으며 특정 쿼리의 컨텍스트에서만 의미가 있습니다.

대부분의 시맨틱 검색 사례의 경우 'min_score'를 적용하기 전에 정규화 접근 방식을 사용하는 것이 좋습니다. 정규화는 문서 점수가 정의된 간격 내에 있도록 보장합니다. Elasticsearch 검색기는 'l2_norm'과 'minmax'라는 두 가지 정규화 도구를 제공합니다. 가장 일반적으로 사용되는 것은 'minmax'입니다. 이해하기 쉽고 많은 시나리오에서 잘 작동하기 때문입니다. 'minmax'의 주요 속성은 다음과 같습니다.

• 문서 점수는 0–1점 사이로 분포됩니다.
• 가장 높은 점수를 받은 문서는 항상 1점으로 처리됩니다.
• 가장 낮은 점수를 받은 문서는 항상 0점으로 처리됩니다.
  • 이로 인해 키워드 검색에 적합하지 않을 수 있습니다. 자세한 내용은 '하이브리드 검색' 섹션을 참조하세요.

다음은 min_score 을(를) 사용하여 정규화된 시맨틱 쿼리의 예입니다. 검색 결과 목록을 100개부터 시작하는 더 긴 목록으로 반환할 수 있도록 순위 창 크기를 500으로 늘렸습니다.

GET search-movies/_search
{
  "size": 100,
  "_source": [
    "title", "overview"
  ],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        }
      ]
    }
  }
}

이 크기는 실제 프로덕션 환경에서 일반적으로 사용되는 값보다 크게 설정되었습니다. 이는 검색 결과의 품질을 검사하고 결과를 조정하기 위한 것입니다.

선형 검색기를 사용한 하이브리드 검색

하이브리드 검색의 경우 가장 간단한 접근 방식은 모든 점수를 정규화하고 가중치를 부여한 다음 최소 점수를 적용하는 것입니다. 합이 1인 가중치를 선택하면 총점이 0–1 범위 내에 유지됩니다. 이렇게 하면 최종 점수를 쉽게 파악하고 min_score 을(를) 조정할 수 있습니다. 다음은 그 예입니다.

GET search-movies/_search
{
  "size": 100,
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "linear": {
      "rank_window_size": 500,
      "min_score": 0.25,
      "retrievers": [
        {
          "weight": 0.6,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "overview_vector",
                  "query": "superhero movie"
                }
              }
            }
          }
        },
        {
          "weight": 0.4,
          "normalizer": "minmax",
          "retriever": {
            "standard": {
              "query": {
                "multi_match": {
                  "query": "superhero movie",
                  "fields": ["overview","keywords", "title"],
                  "type": "cross_fields",
                  "minimum_should_match": "2"
                }
              }
            }
          }
        }
      ]
    }
  }
}

RRF를 사용한 하이브리드 검색

BM25에서는 종종 AND 연산자나 minimum_should_match 와(과) 같은 다른 수단을 통해 정밀도를 제어하기도 합니다. 또한 단일하고 정확하며 희귀한 용어로 구성된 쿼리는 자연스럽게 검색 결과 수가 적고, 그 결과가 모두 관련성이 높은 경우가 많습니다. 이는 다음과 같은 결과로 이어질 수 있습니다.

• BM25 검색기에서 결과 뒷부분에 있는 결과는 절대 BM25 점수가 최고 점수에 근접하더라도 낮은 정규화 점수를 받게 됩니다.
• 매우 낮은 BM25 점수를 시맨틱 점수에 더하면 총점이 시맨틱 점수와 거의 같아집니다.
• BM25 점수 기여도가 부족하면 min_score threshold 에 의해 문서가 폐기될 수 있습니다.

이에 대한 해결책으로 상호 순위 융합(RRF)을 사용하여 BM25와 시맨틱 결과를 결합할 수 있습니다. RRF는 서로 다른 검색 알고리즘의 점수를 비교하는 문제를 해결하기 위해 각 결과 집합에서의 위치에 초점을 맞춥니다. 이 시나리오에서는 min_score 이(가) 시맨틱 검색기에만 적용됩니다.

GET search-movies/_search
{
  "_source": ["title", "overview","keywords"],
  "retriever": {
    "rrf": {
      "rank_window_size": 500,
      "retrievers": [
        {
          "linear": {
            "rank_window_size": 500,
            "min_score": 0.25,
            "retrievers": [
              {
                "normalizer": "minmax",
                "retriever": {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "overview_vector",
                        "query": "superhero movie"
                      }
                    }
                  }
                }
              }
            ]
          }
        },
        {
          "standard": {
            "query": {
              "multi_match": {
                "query": "superhero movie",
                "fields": ["overview", "keywords","title"],
                "type": "cross_fields",
                "minimum_should_match": "2"
              }
            }
          }
        }
      ]
    }
  }
}

결론

min_score을(를) 사용하여 시맨틱 검색 알고리즘의 높은 재현율로 인해 발생하는 결과 집합의 오탐 수를 줄이는 방법을 보여주었습니다. 검색기에 대해 자세히 알아보려면 이 블로그 게시물과 Elasticsearch 설명서를 참조하세요.

Elastic의 종속성 관리

Elastic에서는 비공개 및 공개를 포함하여 수백 개, 심지어 수천 개의 리포지토리를 관리해야 합니다. 중요한 CVE가 발견되면 여러 질문에 대한 즉각적인 답변과 조치가 필요합니다. '어떤 리포지토리가 취약한가?', '얼마나 빨리 패치를 적용할 수 있는가?' 등이 있습니다. 보안 문제 외에 '수작업에 너무 많은 시간을 들이지 않고 새 패키지 버전의 릴리스를 해당 패키지에 의존하는 모든 리포지토리에 신속하게 전파하는 방법은 무엇인가?'라는 생산성 관련 질문도 제기됩니다.

종속성 관리 방법을 모색하게 된 초기 계기는 CVE 감소를 위해 자동화된 업데이트와 함께 안전한 기반을 구축해야 하는 필요성 때문이었습니다. 종속성 관리 솔루션을 신중하게 검토한 후, 우선 자체 호스팅된 인프라 구축에 착수했습니다. Mend Renovate Community 셀프 호스팅 에디션을 실행하기 위해 자체 Kubernetes 클러스터를 사용하고 있었습니다. 사용자들이 셀프 서비스 방식으로 접근할 수 있는 종속성 관리 플랫폼을 제공하는 것이 아이디어의 핵심이었습니다.

초기 실험이 성공적이었기 때문에 점점 더 많은 팀이 플랫폼에 온보딩하여 일상적인 리포지토리의 수명 주기에서 업데이트 및 CVE 패치에 이를 사용하기 시작했습니다. 이 과정이 너무 빨리 진행되어 곧 자체 호스팅 설치 용량의 한계에 도달했습니다.

과제: 대규모 조직에서 수많은 리포지토리를 관리할 때, 종속성 관리 플랫폼을 어떻게 확장할 수 있을까요?

기존 종속성 관리 플랫폼은 한 번에 하나의 리포지토리만 처리할 수 있었고, 수많은 리포지토리로 인해 순차적 처리 모델로는 대처할 수 없었습니다. 우리는 종속성 관리 도구의 단일 인스턴스로 점점 커지는 리포지토리 목록을 처리할 수 있다는 생각 자체에 문제가 있다는 것을 이미 인식하고 있었습니다. 리포지토리는 대기열에서 기다렸고, 때로는 몇 시간이 걸렸습니다. 매일 50% 이상의 리포지토리가 처리되지 않았습니다. 즉, 리포지토리의 50% 이상이 되기까지 24시간 이상 대기해야 했습니다.

대규모 리포지토리는 방대한 코드베이스와 여러 개의 열린 PR로 인해 더 큰 병목 현상을 일으켰습니다. GitHub 웹훅 이벤트는 시퀀스를 중단시켰습니다. Automerge는 스캔 타이밍을 예측할 수 없기 때문에 신뢰할 수 없었습니다. 사용자들에게 스캔 빈도에 대해 약속했지만, 그 약속을 지키지 못했습니다.

자체 구축 결정: Elastic 고유의 확장성 및 보안 요구 사항 충족

Mend의 Renovate Self-Hosted Enterprise 셀프 호스팅 에디션을 포함한 상용 옵션을 고려하면서, Elastic 내부적으로는 몇 가지 주요 이니셔티브를 강화하고 있었습니다.

Elastic의 타협할 수 없는 특정한 요구 사항을 충족할 수 있는 심도 깊은 맞춤형 솔루션만이 유일한 해결책이라는 인식에 따라 자체 플랫폼을 구축하기로 결정했습니다.

1. 내부 개발자 플랫폼 투자: 당시 내부 개발자 플랫폼에 대해 이미 대규모 투자를 시작한 상태였습니다. 각 서비스를 여기에 조화시키는 방식에 대해 논의하고 설계했습니다. 즉, 자체적으로 만든 종속성 관리 플랫폼의 규칙과 관행을 시험적으로 적용해 보고자 했습니다. 게다가 새로운 가이드라인이 시행될 예정이었기 때문에, 그 전에 플랫폼을 설계하고 싶었습니다.
2. 네이티브 통합 및 워크플로우 맞춤 설정: 내부 도구 및 내부 프로세스와의 간편한 통합이 필요했습니다. 예를 들어, 서비스 카탈로그(Backstage)를 사용하여 구성을 코드로 중앙 집중화하고자 했습니다. Backstage의 사용에 관한 특정 요구 사항이 있었으며 플랫폼이 이러한 요구 사항과 호환되기를 원했습니다. 따라서 Renovate 셀프 호스팅 API를 Backstage 자동화와 함께 사용하는 것이 가능하지만, 이것으로는 내부 프로세스를 완전히 지원할 수 없습니다.
3. Elastic에 특화된 심층 방어 보안: 엄격한 보안 규정 준수를 위해서는 에코시스템에 맞춘 맞춤형 보안 메커니즘이 필요했습니다. 우리는 "비인간 ID"의 사용을 강화하기 위해 노력하고 있었습니다. 이러한 액세스 강화 방식으로 인해 비표준적인 GitHub 인증 수단은 이 내부 구현을 지원하지 않는 기성 도구에서는 작동하지 않았습니다. 워크플로우에는 부모-자식 워크플로우 비밀 암호화 패턴 구현과 일시적인 일회성 GitHub 토큰 사용이 포함되었습니다. 자체 구축이 이러한 고유한 보안 계층을 내장하고 복잡한 멀티클라우드 환경 전반에 걸쳐 공격 표면을 최소화하는 유일한 현실적인 방법이었습니다.

해결책: 종속성 관리를 위한 워크플로우 오케스트레이션

솔루션은 이미 사용 중인 종속성 관리 도구를 대체하거나 다른 솔루션을 찾지 않고 이를 기반으로 구축한다는 데서 출발했습니다. 이는 가능성의 징후를 보였으며, 조직 전반에 걸쳐 다양한 요구에 맞추는 유연성이 중요했습니다. 다양한 솔루션을 고려했으며, 우리가 충족해야 할 중대하고 때로는 특별한 요구 사항을 토대로 결정을 내릴 수 있었습니다. 각 리포지토리가 독립적으로 처리되어 병목 현상이 발생하지 않고 성장을 위한 기반을 제공할 수 있도록 신뢰할 수 있고 확장성 있는 종속성 관리 플랫폼을 구축하기로 결정했습니다.

세 가지 핵심 원칙에 따라 플랫폼을 설계했습니다.

1. 병렬 처리

모든 리포지토리는 자체 종속성 관리 처리 환경을 갖습니다. 더 이상 대기열이 없습니다. 동시성은 사용하는 리소스의 수에 의해서만 제한됩니다. 또한 GitHub 속도 제한을 피하기 위해 스마트 분산 스케줄링을 적용했습니다.

2. 셀프 서비스 가능

서비스 카탈로그(백스테이지)를 사용하여 새로운 리포지토리를 자동으로 온보딩하고 관리합니다. 자체 리소스 정의를 사용하여 최종 사용자에게 리포지토리 처리 빈도, 스케줄에 할당할 리소스 수, 그리고 어떤 이유로든 처리를 끌지 아니면 다시 켤지 선택할 수 있는 옵션을 제공합니다. 사용자 요구 사항이 발전하고 새로운 설치 환경에 익숙해짐에 따라 이러한 방식으로 더 많은 옵션을 추가할 계획입니다.

3. 비밀 범위 축소 및 네임스페이스 격리

보안 강화를 위해, 각 워크플로우 시작 시 생성되는 임시 GitHub 토큰을 종속성 관리 포드에 제공합니다. 그뿐만 아니라, 필요한 비밀 키만 제공받을 수 있도록 워크로드를 특정 네임스페이스로 격리합니다. Kubernetes RBAC를 사용하여 각 종속성 관리 워크플로우에서 액세스할 수 있는 비밀 정보를 제어합니다. 또한 GitHub 토큰을 부모 워크플로우에서 자식 워크플로우로 전파할 때 암호화를 사용합니다.

Kubernetes를 사용하여 플랫폼을 재구축했으며, Kubernetes의 강력한 기능을 활용해 Argo Workflows는 프로세스 로직을 강화하고, Renovate CLI는 한 번에 하나의 리포지토리를 스캔하고 처리하도록 설정되었습니다.

장점: 검증된 오픈 소스 프로젝트를 독창적인 방식으로 활용하여 모든 프로젝트에 대해 새로운 작동 예제를 제공하는 동시에, 개발 속도를 높이고 팀의 CVE 감소를 강화합니다.

종속성 관리 아키텍처: 4개의 마이크로서비스

이 플랫폼은 맞춤 제작된 4가지 구성 요소로 이루어져 있습니다.

워크플로우 오퍼레이터(Go/Kubebuilder)

3가지 맞춤형 리소스 정의(CRD)를 통해 워크플로우 수명 주기를 관리하는 Kubernetes Operator:

• RepoConfig CRD: 리포지토리 구성을 위한 단일 정보 소스입니다.

다음은 오퍼레이터에서 RepoConfig가 정의되는 방식입니다.

// RepoConfig is the Schema for the repoconfigs API
type RepoConfig struct {
	metav1.TypeMeta `json:",inline"`

	// metadata is a standard object metadata
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty,omitzero"`

	// spec defines the desired state of RepoConfig
	// +required
	Spec RepoConfigSpec `json:"spec"`

	// status defines the observed state of RepoConfig
	// +optional
	Status RepoConfigStatus `json:"status,omitempty,omitzero"`
}

다음은 RepoConfig 인스턴스의 모습입니다.

apiVersion: workflows.elastic.co/v1
kind: RepoConfig
metadata:
  generation: 3
  name: elastic-test-repo
  namespace: dependency-management-operator
spec:
  owner: group:my-team
  renovate:
    config:
      resourceGroup: SMALL
      runFrequency: 4h
    enabled: true
  repository: elastic/test-repo

• 부모 CRD: 예약된 스캔을 위한 CronWorkflows를 관리합니다.

부모 컨트롤러의 조정 루프 내에서 워크플로우 설정이 생성되고 최신 상태로 유지되거나, 필요한 경우 삭제되는지 확인합니다.

먼저 워크플로우에 대한 몇 가지 전역 설정을 가져옵니다.

func (r *ParentReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, parent *workflowsv1.Parent) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Parent", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		RunFrequency:   parent.Spec.RunFrequency,
		ResourceGroups: "parent",
	}

유사한 워크플로우가 동시에 실행되는 것을 방지하기 위해 mutex configmap이 최신 상태인지 확인합니다.

	cfMngr := resources.NewConfigMapManager(r.Client, r.Scheme, r.OperatorConfig.ParentNamespace)
	err := cfMngr.CreateOrUpdateSyncMutexConfigmap(ctx, fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), strings.TrimPrefix(parent.Spec.Repository, "elastic/"), r.OperatorConfig.SemaphoreConcurrencyLimit)

그런 다음 CronWorkflows와 워크플로우 템플릿을 생성하거나 업데이트하는 구조체인 Workflow Manager를 생성합니다.

	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(parent.Spec.Repository, "/", "-"),
		),
		parent.Namespace,
		"parent-workflow",
		false).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithRepoName(parent.Spec.Repository).
		Init(true, true).
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithWfTemplateName(r.OperatorConfig.ParentWorkflowTemplate).
		WithResources(wfSet.GetResourceCategory()).
		WithSchedule(wfSet.GetCronSchedule()).
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddArgument(true, true, "extra_cli_args").
		SetArgument(true, false, "extra_cli_args", "none").
		AddTemplate(resources.NewParentDAGTemplateInstance()).
		AddTemplate(resources.NewWorkflowsTemplateInstance("check-child-workflows", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("security", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddTemplate(resources.NewWorkflowsTemplateInstance("submit-child-workflow", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector))
	wfMngr.OverWriteCommand("submit-child-workflow", r.OperatorConfig.ChildNamespace)
	wfMngr.OverwriteWfTemplateName("parent-wftmpl")
	wfMngr.AddSynchronization(fmt.Sprintf("%s%s", r.OperatorConfig.ResourcesPrefix, r.OperatorConfig.SyncMutexCfgMapName), "{{workflow.parameters.repo_name}}")
	err = wfMngr.CreateOrUpdateCronWorkflow(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update cron workflow: %w", err)
	}
	err = wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil

• 자식 CRD: 리포지토리별 리소스로 워크플로우 템플릿을 관리합니다.

자식 컨트롤러는 부모와 유사한 조정 의무를 가지고 있지만, 이번에는 부모 워크플로우에 의해 트리거될 자식 네임스페이스의 워크플로우 템플릿에 대한 책임이 있습니다.

func (r *ChildReconciler) reconcileSubResources(ctx context.Context, req ctrl.Request, child *workflowsv1.Child) error {
	logger := logf.FromContext(ctx)
	logger.Info("Reconcile SubResources for Child", "name", req.NamespacedName)
	wfSet := workflowsettings.WorkflowSettings{
		ResourceGroups: child.Spec.ResourceCategory,
	}
	wfMngr := resources.NewArgoWorkflowManager(r.Client,
		r.Scheme,
		curateResourceName(
			strings.ReplaceAll(child.Spec.Repository, "/", "-"),
		),
		child.Namespace,
		"runner",
		true).
		Init(false, true). // only manage workflow template
		WithPrefix(r.OperatorConfig.ResourcesPrefix).
		WithSuffix("-child-wftmpl").
		WithRepoName(child.Spec.Repository).
		WithOrganization(r.OperatorConfig.GitHubOrg).
		WithResources(wfSet.GetResourceCategory()). // will override resources of presets if set
		WithImagePullSecrets([]corev1.LocalObjectReference{{
			Name: r.OperatorConfig.WorkflowImagePullSecrets,
		}}).
		AddTemplate(resources.NewWorkflowsTemplateInstance("runner", r.OperatorConfig.WorkflowImagePullPolicy, r.OperatorConfig.WorkflowNodeSelector)).
		AddArgument(false, true, "repo_full_name").
		AddArgument(false, true, "repo_name").
		AddArgument(false, true, "encrypted_token").
		AddArgument(false, true, "extra_cli_args")
	wfMngr.OverWriteCommand("runner", r.OperatorConfig.ChildNamespace)
	err := wfMngr.CreateOrUpdateWorkflowTemplate(ctx)
	if err != nil {
		return fmt.Errorf("failed to create or update workflow template: %w", err)
	}
	return nil
}

멀티 컨트롤러 패턴은 명확한 분리를 제공합니다. RepoConfig 컨트롤러는 온보딩/오프보딩을 처리하고, 부모 컨트롤러는 스케줄링을 관리하며, 자식 컨트롤러는 실행 템플릿을 처리합니다.

GitHub Events Gateway(Go)

GitHub 웹훅을 수신하고 서명을 확인하고 조직/리포지토리별로 필터링한 후 Argo Events로 라우팅하는 안전한 웹훅 프록시입니다. 종속성 대시보드 상호 작용, PR 이벤트 및 패키지 업데이트에 반응하는 10개의 서로 다른 센서를 구축했습니다.

이 게이트웨이는 다음을 통해 GitHub 앱과 통합할 수 있도록 지원합니다.

• 보안을 위해 수신되는 GitHub 웹훅 서명을 확인합니다.
• 유효한 이벤트를 모든 관련 헤더 및 인증 정보와 함께 Argo Events EventSource로 전달합니다.
• 또한 EventSource에 authSecret을 구성하고 전달된 요청의 Bearer 헤더로 이를 제공합니다.
• 로깅, 메트릭 및 재시도 로직을 제공합니다.

각 GitHub 이벤트 요청에 대해 다양한 검증을 수행합니다.

일부 HTTP 속성이 있는지 확인합니다:

// ValidateRequestMethod checks if the request method is POST.
func ValidateRequestMethod(r *http.Request) error {
	if r.Method != http.MethodPost {
		return fmt.Errorf("method not allowed, only POST is accepted")
	}
	return nil
}

// ValidateRequiredHeaders checks for required GitHub headers.
func ValidateRequiredHeaders(r *http.Request) error {
	eventType := r.Header.Get("X-GitHub-Event")
	deliveryID := r.Header.Get("X-GitHub-Delivery")
	signature := r.Header.Get("X-Hub-Signature-256")
	if eventType == "" || deliveryID == "" || signature == "" {
		return fmt.Errorf("missing required GitHub headers")
	}
	return nil
}

// ValidateUserAgent checks that the User-Agent header starts with GitHub-Hookshot/
func ValidateUserAgent(r *http.Request) error {
	userAgent := r.Header.Get("User-Agent")
	if !strings.HasPrefix(userAgent, "GitHub-Hookshot/") {
		return fmt.Errorf("invalid User-Agent")
	}
	return nil
}

또한 각 요청의 서명과 그 구성도 검증합니다.

// ValidateSignature verifies the GitHub webhook signature.
func ValidateSignature(r *http.Request, secret string) ([]byte, error) {
	payload, err := GitHub.ValidatePayload(r, []byte(secret))
	if err != nil {
		return nil, fmt.Errorf("invalid GitHub signature: %w", err)
	}
	return payload, nil
}

// ValidateAllowedOwner checks if the organization login is in the allowed organizations list.
func ValidateAllowedOwner(payload []byte, allowedGitHubOrganizations []string) (string, error) {
	var orgLogin string
	var payloadMap map[string]any
	if err := json.Unmarshal(payload, &payloadMap); err == nil {
		if orgObj, ok := payloadMap["organization"].(map[string]any); ok {
			if login, ok := orgObj["login"].(string); ok {
				orgLogin = login
			} else if name, ok := orgObj["name"].(string); ok {
				orgLogin = name
			}
		}
	}
	if !slices.Contains(allowedGitHubOrganizations, orgLogin) {
		return orgLogin, fmt.Errorf("organization login not allowed")
	}
	return orgLogin, nil
}

마지막으로 이벤트 유형에 따라 Argo Events로 라우팅됩니다.

	// Map eventType to Argo `EventSource` path
	var endpoint string
	switch eventType {
	case "push":
		endpoint = "/push"
	case "issues":
		endpoint = "/issues"
	case "pull_request":
		endpoint = "/pull-requests"
	default:
		slog.Info("Ignoring unhandled event type", "event_type", eventType, "delivery_id", deliveryID)
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
		return
	}
	forwardURL := h.config.ArgoEventSourceForwardURL + endpoint

Argo Events 측에서는 10개의 센서가 새로운 이벤트를 감지하기 위해 Argo Events EventBus를 모니터링합니다.

apiVersion: argoproj.io/v1alpha1
kind: Sensor
metadata:
  name: {{ .Values.sensors.packageUpdateOnDefaultBranch.name }}
  namespace: {{ .Release.Namespace }}
spec:
  eventBusName: {{ .Values.eventBus.name }}

그 후 스크립트는 각 센서의 논리를 적용합니다:

script: |
          local e = event
          if not e or not e.body or not e.body.repository then
            return false
          end

          -- e.g., "refs/heads/main"
          local ref = e.body.ref
          local default_branch = e.body.repository.default_branch
          if not ref or not default_branch then
            return false
          end

          local expected = "refs/heads/" .. default_branch
          if ref ~= expected then
            return false
          end

        {{- if .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}
          patterns = { {{- range $i, $f := .Values.sensors.packageUpdateOnDefaultBranch.packageFiles }}{{ if $i }}, {{ end }}"{{ $f }}"{{- end }} }
        {{- end }}

          local function anyMatch(path)
            if type(path) ~= "string" then return false end
            for _, pat in ipairs(patterns) do
              -- match filename at repo root, or anywhere under subdirs
              if path:match(pat) or path:match(".+/" .. pat) then
                return true
              end
            end
            return false
          end

          local function filesContainPackage(paths)
            if type(paths) ~= "table" then return false end
            for _, p in ipairs(paths) do
              if anyMatch(p) then return true end
            end
            return false
          end

          -- Inspect all commits (GitHub includes added/modified/removed lists)
          local commits = e.body.commits
          if type(commits) ~= "table" then
            -- Fallback: some payloads include only head_commit
            commits = {}
            if type(e.body.head_commit) == "table" then
              table.insert(commits, e.body.head_commit)
            end
          end

          for _, c in ipairs(commits) do
            if filesContainPackage(c.added) or filesContainPackage(c.modified) or filesContainPackage(c.removed) then
              return true
            end
          end

          return false

Backstage Syncer(Go)

이 작업은 서비스 카탈로그(Backstage)에서 리포지토리 실제 리소스 엔티티를 폴링하고, 이를 RepoConfig CRD로 변환하며, 플랫폼을 구성 변경 사항과 동기화된 상태로 유지합니다. 변경 사항은 3분 이내에 적용됩니다.

repoMap := make(map[string]map[string]interface{})
			for i := range entities {
				entity := &entities[i]
				if entity.Spec.Type != "GitHub-repository" {
					continue
				}

				implRaw, err := json.Marshal(entity.Spec.Implementation)
				if err != nil {
					logger.Error("Failed to marshal implementation", "error", err)
					continue
				}

				var implMap map[string]interface{}
				err = json.Unmarshal(implRaw, &implMap)
				if err != nil {
					logger.Error("Failed to unmarshal implementation map", "error", err)
					continue
				}
				var repoName string
				if specMap, ok := implMap["spec"].(map[string]interface{}); ok {
					if repo, ok := specMap["repository"].(string); ok {
						repoName = repo
					}
				}
				if repoName == "" {
					continue
				}

				var workflowsRaw []byte
				if v, ok := implMap["spec"].(map[string]interface{}); ok {
					if r, ok := v["renovate"]; ok {
						workflowsRaw, _ = json.Marshal(r)
					} else {
						workflowsRaw = []byte(`{}`)
					}
				} else {
					workflowsRaw = []byte(`{}`)
				}

				var workflowsWithDefaults schema.WorkflowsMetadata
				err = json.Unmarshal(workflowsRaw, &rworkflowsWithDefaults)
				if err != nil {
					logger.Error("Failed to unmarshal workflows config", "error", err)
					continue
				}

				workflowsMap := map[string]interface{}{
					"enabled":        workflowsWithDefaults.Enabled,
					"require_pr":     workflowsWithDefaults.RequirePr,
					"resource_group": string(workflowsWithDefaults.ResourceGroup),
					"run_frequency":  string(workflowsWithDefaults.RunFrequency),
				}
				repoMap[repoName] = map[string]interface{}{
					"renovate": workflowsMap,
					"owner":    entity.Spec.Owner,
				}
			}
			logger.Info("Fetched GitHub Repository data from Backstage", "repository_count", len(repoMap), "status_code", resp.StatusCode)

마지막으로 해당 데이터를 RepoConfig 인스턴스에 기록합니다.

워크플로우 베이스(혼합: JavaScript, Go, Helm)

기반 레이어에는 Helm 차트, JavaScript 구성, 암호화 지원 기능을 갖춘 Renovate CLI용 Go 래퍼, 그리고 Alpine 패키지용 맞춤형 APK 인덱서가 포함되어 있습니다.

셀프 서비스 구성

팀은 Backstage를 통해 리포지토리를 선언적으로 구성합니다.

spec:
  renovate:
    enabled: true
    config:
      resourceGroup: LARGE      # SMALL | MEDIUM | LARGE  
      runFrequency: "0 */4 * * *"  # Every 4 hours

리소스 그룹은 리포지토리 크기에 따라 CPU와 메모리를 할당합니다.

• SMALL: 500m CPU, 1Gi 메모리.
• MEDIUM: 1000m CPU, 2Gi 메모리.
• LARGE: 2000m CPU, 4Gi 메모리.

구성은 버전이 제어되고 감사 가능하며 자동으로 적용됩니다.

부모-자식 패턴

실행 모델은 부모-자식 워크플로우 패턴을 사용합니다.

• 부모 워크플로우: 예약된 시간에 실행되는 경량 CronWorkflow입니다. 비밀 정보를 암호화하고, 검사 실행 여부를 결정하며, 구성 정보를 자식 워크플로우에 전달합니다.
• 자식 워크플로우: Renovate CLI가 실행되는 임시 포드입니다. 동적으로 리소스를 할당하고, 격리된 상태에서 비밀 정보를 해독하며, 완료 후 종료합니다.

이러한 분리는 보안(부모 레벨에서 암호화된 비밀), 리소스 최적화(부모 레벨에서 최소한의 리소스 사용), 그리고 확장성(자식 레벨에서 병렬 실행)을 제공합니다.

결과

성능 변환

• 이전: 한 번에 하나의 리포지토리만 처리하고, 일부 리포지토리는 하루 이상 처리되지 않기도 했으며, 하루에 1,000건 미만의 스캔이 처리되었습니다.
• 이후: 100개 이상의 동시 스캔, 하루에 보통 8,000개 스캔, 최대 10,000개의 기록된 스캔이 이루어지며, 사용 가능한 리소스의 양과 GitHub 속도 제한을 처리하는 방법에 의해서만 제한됩니다.

비용 효율성

이상하게 들릴지 모르지만, 하루에 8,000개의 포드를 실행하는 것이 동일한 결과를 달성하기 위해 하나의 장기 실행 포드를 사용하는 것보다 훨씬 저렴할 수 있습니다.

이전 설정에서는 단일 인스턴스를 운영했고, 양호한 날에는 500~600번의 스캔을 수행했습니다. 또한, 서로 다른 종류의 리포지토리가 같은 포드에서 실행되기 때문에 가장 큰 리포지토리에 맞게 포드 크기를 조절해야 했습니다. 이는 포드용 CPU 8개와 16G 메모리를 사용하는 현재보다 훨씬 규모가 커질 수 있습니다.

현재의 일일 출력을 충족하려면 단일 포드는 12일 동안 실행되어야 합니다. 12일 동안 실행되는 단일 포드의 비용을 매일 실행되는 8,000개의 “MEDIUM” 크기 포드와 비교하면, 동일한 스캔 출력에서 새로운 설계가 훨씬 더 효율적입니다.

이제 워크로드 기본값이 "SMALL"로 설정되어 있으며, 대다수가 0.5 CPU와 1G RAM으로 성공적으로 실행되고 소수만 중간, 대형으로 변경해야 하는 경우를 생각해 보겠습니다. 작업 부하의 60%가 "SMALL", 30%가 "MEDIUM", 그리고 10%가 "LARGE"에서 실행된다면 어떻게 되는지 살펴봅시다. 이는 실제 상황에 더 가깝습니다.

동일한 출력을 얻을 때 현재 설정이 훨씬 더 비용 효율적이라는 것을 알 수 있습니다.

보안 강화

• 일시적인 GitHub 토큰(노출 시간이 일 단위가 아닌 분 단위)
• 역할 기반 액세스 제어(RBAC) 경계를 사용한 네임스페이스 격리
• 부모 워크플로우에서 저장 데이터 비밀 암호화
• 직접 볼트 액세스 제거

예측 가능한 성능

스캔 빈도가 보장되어 마침내 서비스 수준 목표(SLO)를 설정할 수 있습니다. Automerge는 안정적으로 작동합니다. 팀은 플랫폼이 약속대로 실행될 것이라고 신뢰합니다.

주요 설계 결정 사항

다음은 플랫폼의 모습을 형성하는 데 중요한 역할을 한 몇 가지 주요 설계 결정 사항입니다.

• 부모-자식 워크플로우를 사용하는 이유는 무엇인가요?

심층 방어 전략을 실행하기 위해 이 패턴을 채택했습니다. 중요한 자격 증명(예: GitHub 앱 비밀)을 잠긴 전용 네임스페이스로 제한함으로써 임시 실행 포드가 민감한 데이터에 임의로 액세스할 수 없도록 하기 위해 RBAC를 사용합니다. 최근의 공급망 취약성(예: "Shai Hulud" 지속적 통합/지속적 배포[CI/CD] 공격)은 자격 증명 저장소에서 동적 스크립트를 실행하는 런타임 환경을 격리하는 것이 얼마나 중요한지를 보여주었습니다.

동시에 이러한 분리를 통해 세분화된 리소스 최적화가 가능합니다. "부모" 워크플로우는 최소한의 풋프린트로 가벼운 오케스트레이터 역할을 하는 반면, "자식" 워크플로우는 컴퓨팅 집약적인 종속성 스캐닝을 처리합니다. 이러한 분리는 수명 주기 관리를 단순화하여 각 계층에 별개의 조정 로직을 적용할 수 있게 하므로, 사용자는 실행 매개 변수(자식)에 대한 제어권을 갖는 반면 관리자는 스케줄링 및 보안 인프라(부모)에 대한 관리 제어권을 유지할 수 있습니다.

• 셀프 서비스를 사용하는 이유는 무엇인가요?

팀이 리포지토리 구성의 병목 현상이 되지 않도록 하는 것은 중요한 요구 사항이었습니다. 다양한 사용 사례를 지원할 수 있는 확장 가능한 셀프 서비스 플랫폼을 구축하는 것이 목표였습니다. 우리는 엄청난 양의 리포지토리를 고려할 때, 모든 구성 변경에 대해 게이트키퍼 역할을 하는 것은 지속 불가능하다는 것을 인식했습니다. 대신, 사용자가 "열차"를 운전할 수 있도록(실행 및 맞춤화) "레일"(인프라 및 가드레일)을 제공한다는 지원 철학을 채택했습니다. 이와 같이 팀 자율성으로 전환하여 사용자가 시스템을 특정 운영 요구 사항에 맞게 조정할 수 있도록 하면 생산성이 크게 향상된다고 믿습니다.

• Kubernetes Operator 패턴을 사용하는 이유는 무엇인가요?

위에서 언급했듯이, 기본적인 설계 원칙은 플랫폼이 완전히 셀프 서비스 가능하도록 하는 것이었습니다. 사용자 의도(스캔 전환, 일정 주기 조정, 런타임 리소스 제한 조정 등)를 파악하고 변경 사항을 기본 워크플로우에 즉시 전파하려면 자동화된 메커니즘이 필요했습니다. 또한 향후 요구 사항을 예상하여 시스템은 쉽게 확장 가능해야 했습니다.

이를 위해 맞춤형 종속성 관리 Kubernetes Operator를 개발했습니다. CRD를 구성 인터페이스로 사용함으로써, Kubernetes 네이티브 조정 루프를 구축했습니다. 이 오퍼레이터는 사용자가 정의한 원하는 상태를 지속적으로 모니터링하고, 워크플로우 인프라에 필요한 업데이트를 자동으로 오케스트레이션합니다. 이를 통해 플랫폼 로직이 모든 복잡한 작업을 백그라운드에서 처리하므로 이벤트 기반의 원활한 작동이 보장됩니다.

• GitHub Events Gateway를 설계하는 이유는 무엇인가요?

플랫폼의 응답성을 위해 이벤트 기반 아키텍처 (EDA) 채택이 필수적이었습니다. CronWorkflows는 신뢰할 수 있는 기준 일정을 제공했지만, 사용자가 대시보드를 통해 수동으로 스캔을 트리거하는 등 임시 실행을 처리할 수 있는 민첩성이 필요했습니다. 이를 위해서는 페이로드 무결성을 검증하고 요청을 지능적으로 라우팅할 전용 수집 게이트웨이가 필요했습니다.

우리는 Argo용 기본 GitHub EventSource를 포함한 기존 솔루션을 평가했지만, 운영 오버헤드 및 엄격한 GitHub API 할당량(예: 리포지토리당 웹훅 제한)과 관련하여 상당한 위험이 있음을 확인했습니다. 결과적으로 이러한 제한으로부터 인프라를 분리하기 위해 맞춤형 게이트웨이를 구축했습니다.

무엇보다도, 이 게이트웨이는 마이그레이션 중에 전략적인 트래픽 제어 지점 역할을 했습니다. 이는 기존 시스템에서 새로운 인프라로 점진적이고 세분화된 배포(트래픽 전환)를 수행할 수 있도록 스위치 역할을 했습니다. 이를 통해 수천 개의 리포지토리를 온보딩하는 과정이 "빅뱅" 전환 방식이 아닌 통제되고 위험 없는 프로세스로 수행되었습니다.

얻은 교훈

우리가 얻은 몇 가지 교훈은 Elastic 소스 코드와 밀접한 관련이 있습니다.

1. 고객 우선: 플랫폼은 사용자를 위해 구축됩니다. 따라서 사용자의 요구를 최우선으로 고려하는 것이 중요합니다. 이를 통해 플랫폼을 효율적으로 설계된 인프라와 애플리케이션으로 형성하여 사용자와의 마찰을 줄이고, 플랫의 확장을 단순화하며 원활한 도입일 촉진할 수 있습니다.
2. 공간, 시간: 저항이 가장 적은 경로는 때때로 불안정한 상황으로 이어지곤 합니다. 처음에는 기존의 순차적 처리 모델을 최적화하려고 했지만, 이것으로 문제를 해결할 수 없었습니다. 오히려 더 많은 복잡성과 미해결 문제를 초래했습니다. 병렬 처리로 플랫폼을 재설계하기로 한 과감한 결정은 상당한 사전 노력을 필요로 했습니다. 하지만 결과적으로 플랫폼의 지속 가능한 성장을 위한 길을 열었고, 지루한 일상적인 관리 업무를 사실상 제거했습니다.
3. IT, 종속성: 플랫폼은 단독으로 운영될 수 없습니다. 플랫폼의 성공은 더 넓은 에코시스템과 얼마나 잘 통합되는지에 달려 있습니다. 이 사례에서는 Backstage와의 통합이 매우 중요했습니다. 원활한 서비스 온보딩을 위한 정보 소스 역할을 하기 때문입니다. 마찬가지로 Artifactory에 연결하여 개인 패키지 업데이트를 효율적으로 관리할 수 있게 되었습니다. 그 외에도 필수 통합 목록은 계속 이어집니다.
4. 발전, 단순한 완벽함: 구현 과정 전반에 걸쳐 초기 가정에 대해 지속적으로 엄격한 테스트를 수행하고 새로운 장벽이 나타나면 이에 맞게 조정했습니다. 완벽주의에 빠지기보다는 반복 접근 방식을 채택하여 과제를 하나씩 해결하고 실제 환경에 맞게 마이그레이션 전략을 조정했습니다.

그럼 이제 무엇을 해야 할까요?

플랫폼 제공은 더 의미 있는 작업을 가능하게 하여 플랫폼의 UX와 효율성을 향상시키는 데 도움이 됩니다. 몇 가지 예는 다음과 같습니다.

• 자동 병합 도입을 늘리고 가드레일 구축

자동 병합 기능은 지루한 수동 작업을 없애 팀의 작업 속도를 크게 향상시킵니다. 하지만 속도 향상으로 인해 보안이 훼손되지 않도록 엄격한 가드레일을 마련해야 합니다.

• 최종 사용자 경험에 대한 통합 가시성 향상

로드맵의 중요한 우선순위는 플랫폼 수준뿐만 아니라 특히 최종 사용자의 관점에서 통합 가시성을 강화하는 것입니다. 인프라 메트릭을 파악하는 것은 간단하지만, 실제 사용자 경험을 이해하려면 더 심층적인 인사이트가 필요합니다. 우리는 사용자 불만으로 이어지기 전에 원격 측정 데이터를 통해 문제점과 성능 문제를 탐지할 수 있도록 사용자 중심의 핵심 성과 지표(KPI)를 정의하고 있습니다.

• 장벽을 제거하여 도입 촉진

앞으로 최우선 과제는 플랫폼 도입을 방해하는 모든 장벽을 파악하고 제거하는 것입니다. 새로운 통합 기능을 개발하든 특정 기능 세트를 배포하든, 데이터 기반 계획 수립에 전념합니다. 확장성을 고려하여 설계된 플랫폼을 성공적으로 구축했으며, 이제 그 잠재력을 극대화하는 데 집중하고 있습니다.

더 큰 그림

종속성 관리 워크플로우 프로젝트는 더 광범위한 원칙을 제시합니다. 오픈 소스 도구를 기본 배포 모델 이상으로 확장해야 할 때 Kubernetes 네이티브 패턴이 해결책을 제시한다는 것입니다.

수용함으로써:

• 구성용 CRD
• 수명 주기 관리를 위한 오퍼레이터
• 응답성을 위한 이벤트 중심 아키텍처
• 배포용 GitOps

관리하는 리포지토리 수와 관계없이 확장 가능한 오케스트레이션을 구축했습니다. 하나의 리포지토리를 스캔하는 성능은 100개를 관리하든 1,000개를 관리하든 동일합니다.

중요한 CVE가 발표되면 이제 몇 시간이 아니라 몇 분 만에 답변을 받을 수 있습니다. 이것이 병목 현상과 경쟁 우위의 차이입니다.

감사의 말씀

이 플랫폼은 뛰어난 오픈 소스 도구를 기반으로 구축되었습니다.

• Kubebuilder: 워크플로우를 부트스트랩하고 오케스트레이션하는 Kubernetes Operator를 시작하는 데 사용한 오픈 소스 프레임워크입니다. [1][2]
• Backstage: 서비스 카탈로그를 구축하는 데 신뢰할 수 있는 정보 소스로 사용한 오픈 소스 프레임워크입니다. [1][2]
• Argo Workflows 및 Argo Events: 복잡한 프로세스를 오케스트레이션하고 이벤트에 기반한 동적 처리를 추가하는 데 사용한 오픈 소스 제품군입니다. [1][2][3][4]
• Renovate CLI: 리포지토리를 처리하는 오픈 소스 종속성 관리 도구입니다. [1][2]

* AWS Fargate 가격 모델이 단일 포드의 비용을 참조하는 데 사용되었지만, 워크로드가 반드시 AWS에서 실행되는 것은 아니며 완전한 Kubernetes 클러스터에서 실행되고 있습니다.

동시성이 높은 워크로드에 맞게 Elasticsearch를 조정할 때 일반적인 접근 방식은 검색 지연 시간을 줄이기 위해 작업 문서 세트를 메모리에 유지하도록 RAM을 최대화하는 것입니다. 따라서 best_compression 은(는) 주로 저장 공간 효율성이 우선시되는 Elastic Observability와 Elastic Security 사용 사례에서 저장 공간 절약 수단으로 간주되며, 검색 워크로드에는 거의 고려되지 않습니다.

이 블로그에서는 데이터 세트 크기가 OS 페이지 캐시를 크게 초과하는 경우, best_compression 이(가) I/O 병목 현상을 줄여 검색 성능과 리소스 효율성을 개선하는 방법을 보여줍니다.

설정

해당 사용 사례는 Elastic Cloud CPU에 최적화된 인스턴스에서 실행되는 동시성이 높은 검색 애플리케이션입니다.

• 데이터 볼륨: 약 5억 개의 문서
• 인프라: 6개의 Elastic Cloud(Elasticsearch Service) 인스턴스(각 인스턴스: 1.76TB 저장 공간 | 60GB RAM | 31.9 vCPU)
• 메모리 대 저장 공간 비율: 전체 데이터 세트의 약 5%를 RAM에 저장

증상: 긴 지연 시간

19시경에 현재 요청 수가 급증할 때 검색 지연 시간이 크게 악화되는 것을 확인했습니다. 그림 1과 그림 2에서 볼 수 있듯이, Elasticsearch 인스턴스당 분당 약 400건의 요청이 발생하는 최고 트래픽 수준에서 평균 쿼리 서비스 시간은 60ms 이상으로 저하되었습니다.

초기 연결 처리 이후 CPU 사용량은 비교적 낮은 수준을 유지했는데, 이는 컴퓨팅이 병목 현상이 아님을 나타냅니다.

쿼리 볼륨과 페이지 오류 사이에 강한 상관관계가 나타났습니다. 요청량이 증가함에 따라 페이지 오류도 비례적으로 증가하여 분당 약 40만 건에 달하는 최고치를 기록했습니다. 이는 활성 데이터 세트가 페이지 캐시에 저장될 수 없음을 의미합니다.

동시에 JVM 힙 사용량은 정상적인 수준을 보였습니다. 이는 가비지 컬렉션 문제가 아님을 시사하며, 병목 현상이 I/O에 있음을 확인시켜 줍니다.

진단: I/O 바운드

시스템이 I/O 바운드 상태였습니다. Elasticsearch는 OS 페이지 캐시를 활용하여 메모리에서 인덱스 데이터를 제공합니다. 인덱스가 캐시에 비해 너무 크면 쿼리는 값비싼 디스크 읽기를 트리거합니다. 일반적인 해결책은 수평적 확장(노드/RAM 추가)이지만, 먼저 기존 리소스를 활용하여 효율성을 개선하고자 했습니다.

수정 사항

기본적으로 Elasticsearch는 인덱스 세그먼트에 LZ4 압축을 사용하여 속도와 크기 사이의 균형을 유지합니다. best_compression ( zstd 방식 사용)로 전환하면 인덱스 크기가 줄어들 것이라는 가설을 세웠습니다. 설치 공간이 작아지면 페이지 캐시에 더 많은 비율의 인덱스가 들어갈 수 있으므로 압축 해제에 필요한 CPU 사용량의 미미한 증가와 디스크 I/O의 감소를 맞바꿀 수 있습니다.

best_compression 을(를) 활성화하기 위해 인덱스 설정 index.codec: best_compression (으)로 데이터를 다시 색인했습니다. 또는 인덱스를 닫고 인덱스 코덱을 best_compression (으)로 재설정한 다음 세그먼트 병합을 수행해도 동일한 결과를 얻을 수 있습니다.

POST my-index/_close
PUT my-index/_settings
{
    "codec": "best_compression"
}
  
POST my-index/_open  
POST my-index/_forcemerge?max_num_segments=1

결과

결과는 가설을 뒷받침했습니다. 저장 공간 효율성 개선은 CPU 사용률의 증가 없이 검색 성능의 상당한 향상으로 직결되었습니다.

best_compression 을(를) 적용함으로써 인덱스 크기가 약 25% 감소했습니다. 반복적인 로그 데이터에서 나타난 감소율보다는 낮지만, 이 25% 감소는 페이지 캐시 용량을 동일한 수준으로 실질적으로 증가시켰습니다.

다음 로드 테스트(17시 시작) 동안 트래픽은 훨씬 더 높아져 Elasticsearch 노드당 분당 최대 500건의 요청을 기록했습니다.

로드가 높아졌음에도 CPU 사용률은 이전 실행보다 낮았습니다. 이전 테스트에서 사용률이 높았던 것은 과도한 페이지 오류 처리 및 디스크 I/O 관리로 인한 오버헤드 때문이었을 가능성이 큽니다.

결정적으로 페이지 오류가 많이 감소했습니다. 처리량이 높아진 상황에서도 오류 수는 분당 20만 건 미만으로, 기준 테스트의 30만 건 이상에 비해 현저히 줄어들었습니다.

페이지 오류 결과는 여전히 최적에 미치지 못했지만, 쿼리 서비스 시간은 약 50% 단축되었습니다. 로드가 많은 상황에서도 30ms 미만으로 유지되었습니다.

결론: 검색을 위한 best_compression

데이터 볼륨이 사용 가능한 물리적 메모리를 초과하는 검색 사용 사례에서 best_compression은(는) 강력한 성능 조정 수단입니다.

캐시 미스를 해결하는 일반적인 해결책은 RAM을 늘려 확장하는 것입니다. 하지만 인덱스 공간을 줄임으로써 페이지 캐시의 문서 수를 최대화하는 동일한 목표를 달성했습니다. 다음 단계에서는 인덱스 정렬을 통해 저장 공간 최적화를 더 강화하고 기존 리소스에서 성능을 극대화할 것입니다.

에이전트는 효율성 향상과 더 나은 고객 경험을 제공할 수 있는 잠재력으로 인해 주목받고 있습니다. 그러나 실제로는 에이전트에게 적절한 컨텍스트를 제공하기가 쉽지 않으며, 특히 복잡하고 비정형적인 엔터프라이즈 데이터를 처리할 때는 더욱 그렇습니다. 개발자는 도구, 프롬프트, 상태, 추론 논리, 모델을 관리해야 하며, 특히 비즈니스 소스에서 관련 컨텍스트를 검색하여 정확한 결과와 작업을 제공해야 합니다. Elastic Agent Builder는 안전하고 신뢰할 수 있는 컨텍스트 기반 에이전트를 개발하기 위한 핵심 구성 요소를 제공합니다.

Agent Builder의 핵심 기능

Agent Builder는 검색 정확도와 검색 증강 생성 분야에 대한 Elastic의 지속적인 투자와 Elasticsearch를 최적의 벡터 데이터베이스로 만들기 위한 노력을 통해, 맥락적이고 데이터에 초점을 둔 AI 에이전트 개발을 단순화합니다.

Agent Builder로 할 수 있는 일은 다음과 같습니다.

• 질문에 답하고, 분석을 수행하며, Elasticsearch에 있는 모든 데이터를 기반으로 조사까지 진행할 수 있는 기본 제공 대화형 에이전트를 즉시 시작할 수 있습니다.
• 복잡하고 비정형적인 데이터에서 출발해, 설정 기반의 개발 환경을 갖춘 사용자 정의 에이전트로 신속히 전환할 수 있습니다.
• 기본 제공 ES|QL이나 사용자 정의 도구를 활용해 업계 최상급의 하이브리드 검색 정확도를 적용함으로써, 컨텍스트의 품질과 에이전트의 안정성을 높일 수 있습니다.
• 복잡한 워크플로우를 재사용 가능한 도구로 실행하여 데이터 강화, 기록 갱신, 메시지 발송 등 다양한 규칙 기반 자동화를 구현할 수 있습니다(미리보기 버전).
• 워크플로우 및 MCP를 사용하여 Elasticsearch 외부의 데이터 소스에 연결하고 에이전트에 대한 컨텍스트를 상호 연관시키고 결합할 수 있습니다.
• MCP 기반의 기본 제공·사용자 정의 도구를 통해 다양한 에이전틱 및 애플리케이션 프레임워크와 연동할 수 있고, 외부 MCP 연결(미리보기 버전), A2A 지원, 완전한 API 지원을 제공합니다.
• Agent Builder의 기능을 더욱 확장하려면 복잡한 문서 처리에는 LlamaIndex를, 보안성과 구조화를 갖춘 도구 액세스에는 Arcade.dev를 연동할 수 있습니다.

Agent Builder의 기능성을 한층 강화하고자, 새로운 규칙 기반 자동화 기능인 Elastic Workflows를 기술 미리보기로 선보입니다. 조직 차원의 작업에서 에이전트는 특정 비즈니스 로직을 구현하기 위해 규칙 기반 조치의 확실성과 신뢰성이 필요한 경우가 종종 있습니다. Elastic Workflows는 에이전트가 내부·외부 시스템을 오케스트레이션해 조치를 실행하고, 데이터와 컨텍스트를 수집 및 가공할 수 있는 단순한 선언형 방법을 제공합니다. 워크플로는 완벽하게 조합 가능하고, 이벤트 중심 구조와 높은 유연성을 갖추고 있으며, MCP를 통해 에이전트에 도구로 노출될 수 있습니다.

데이터에서 에이전트로 단 몇 분 만에 전환

에이전트 개발은 분산된 데이터 저장소를 통합하고, 수동 파이프라인을 구축하며, 쿼리를 튜닝하고, 복잡한 오케스트레이션을 관리해야 해 초기 단계에서 몇 주가 걸리기도 합니다. Agent Builder는 별도의 데이터 저장소, 벡터 데이터베이스, RAG 파이프라인, 검색 계층, 쿼리 변환기, 도구 오케스트레이터가 필요 없도록 해 주어 에이전트 개발 시간을 단축하고, 에이전트 로직과 애플리케이션 제공에 집중할 수 있게 합니다.

Agent Builder는 Elasticsearch 플랫폼의 기본 구성 요소를 네이티브로 통합해 에이전트 개발을 빠르게 만듭니다.

• 인덱싱된 데이터를 대상으로 즉시 대화하고 추론할 수 있는 기본 제공 대화형 에이전트를 통해 바로 시작할 수 있습니다.
• Kibana, API, MCP, A2A를 통한 대화형 접근을 활용해 에이전트를 애플리케이션, 대시보드 또는 CI/CD 시스템에 통합할 수 있습니다.
• 기본 제공 도구를 활용해 데이터 구조를 이해하고, 적절한 인덱스를 선택하며, 최적화된 하이브리드·시맨틱·구조화 쿼리를 생성하고, 자연어 프롬프트를 기반으로 ES|QL을 사용해 시각화를 유연하게 구성할 수 있습니다.

더 깊이 살펴보려면 전 과정의 실습형 단계별 안내를 활용해 보세요.

컨텍스트 엔지니어링을 위한 완벽한 데이터 플랫폼인 Elasticsearch 기반 구축

AI 에이전트의 경우, 효과적인 추론을 제공하고 환각의 위험을 줄이기 위해서는 컨텍스트의 품질이 매우 중요합니다. 많은 기업용 AI 에이전트에게 있어 작업을 수행하는 데 필요한 비즈니스 데이터는 가장 중요한 컨텍스트 정보입니다. 대규모 확장이 가능한 데이터 저장소이자 벡터 데이터베이스이며 검색 정확도 분야의 선두 주자인 Elasticsearch는 이미 강력한 컨텍스트 엔지니어링 핵심 기능을 다수 제공하고 있습니다. 컨텍스트 엔지니어링은 단순한 검색 증강 생성을 넘어, 데이터 조회·순위화·필터링·표현 방식을 조정 및 확장할 수 있게 하여 에이전트가 받는 잡음과 모호함을 줄이는 데 도움이 됩니다.

Elasticsearch는 어휘 검색, 벡터 검색, 구조화 필터링을 결합한 컨텍스트 엔진을 제공하여 모델이 관련성 높고 정확한 컨텍스트에서 동작하도록 보장해 실질적으로 LLM 성능을 향상시킵니다. 이 기능은 에이전트형 검색을 기반으로 하며, 적절한 인덱스를 자동으로 선택하고 자연어를 컨텍스트에 최적화된 쿼리로 변환하는 기본 제공 도구와 검색 로직이 이를 지원합니다.

Agent Builder를 사용하면 정확도와 순위화를 제어하는 기능을 통해 에이전트가 가장 유용한 컨텍스트를 우선적으로 받도록 할 수 있으며, 점수 매기기·순위화·필터링 로직을 세밀하게 조정할 수 있습니다. Elasticsearch는 불명확한 검색 동작에 의존하는 대신, 무엇이 중요한지, 왜 중요한지, 그리고 어떻게 우선순위를 둘지를 직접 제어할 수 있게 합니다. 이 모든 것은 텍스트, 벡터, 메타데이터, 로그 등 모든 데이터를 하나의 플랫폼에서 저장·확장할 수 있는 확장형 데이터 플랫폼인 Elasticsearch를 기반으로 하여, 에이전트용 컨텍스트 관리를 더욱 용이하게 합니다.

재사용 가능한 도구로 복잡한 워크플로우 실행

AI 에이전트가 복잡한 작업에서 추론을 수행하더라도, 자동화의 상당 부분은 특정 비즈니스 로직을 적용하는 규칙 기반 조치를 안정적으로 실행하는 데 의존합니다. Elastic Workflows는 내부 및 외부 시스템을 오케스트레이션하여 작업을 실행하고 컨텍스트 또는 데이터를 수집한 뒤, 이를 에이전트에 통합할 수 있도록 하는 단순한 선언형 방법을 제공합니다. 워크플로우는 YAML로 정의되며, 완전한 조합 구조를 지원하여 작업 성격에 따라 단순하게도, 복잡하게도 구성할 수 있습니다. 이를 통해 에이전트는 Elasticsearch 플랫폼과 다양한 솔루션, 나아가 서드파티 애플리케이션까지 아우르며 효율적으로 동작할 수 있습니다.

워크플로우를 Agent Builder와 통합하는 과정은 세 단계로 진행할 수 있습니다(전제 조건: 여기 안내된 자세한 내용에 따라 워크플로우 활성화).

1. 기본 제공 자동 완성 및 테스트 기능을 갖춘 간단한 YAML 기반 편집기를 사용하여 새 워크플로우를 생성하고 저장합니다.

2. Agent Builder에서 “워크플로우” 타입의 새 도구를 생성한 뒤, 에이전트가 해당 워크플로우 도구를 사용할 시점을 결정하는 데 도움이 되도록 설명을 입력합니다.

3. 사용자 정의 에이전트에 워크플로우 도구를 추가합니다.

4. 끝입니다! 이제 에이전트가 대화 도중에 워크플로우를 호출할 수 있습니다.

나만의 에이전트, 나만의 규칙

Agent Builder는 하나의 개발 패러다임만을 강요하지 않습니다. 대신 데이터, 정확도, 모델, 상호 운용성, 보안, 에이전트 설계 전반을 완전히 제어할 수 있는 개방적이고 유연한 에이전트 개발 방식을 지원하도록 설계되었습니다.

사용자 지정 에이전트 정의를 사용하면 에이전트가 사용할 수 있는 도구를 명확히 지정하고, 사용자 지정 시스템 프롬프트를 삽입하며, 에이전트 지침을 세밀하게 조정하고 보안 범위를 설정할 수 있습니다. 에이전트는 특정 모델에 종속되지 않으므로, 하나의 제공업체에 의존하지 않고 기본 제공 모델부터 외부 에코시스템의 LLM까지 원하는 대로 자유롭게 설정할 수 있습니다.

도메인별 로직(예: 특정 인덱스 필터, ES|QL 조인, 분석 파이프라인)을 캡슐화한 확장형 도구를 구축하고, 프로덕션 환경에서 안전하게 사용하도록 제약을 설정할 수 있습니다. 완전한 API 지원으로 다른 에이전트형 프레임워크와의 상호 운용이 가능하며, 모델 컨텍스트 프로토콜(MCP)을 기본적으로 지원합니다. A2A 통합을 통해 Elastic 에이전트를 다른 프레임워크, 서비스, 클라이언트 앱에 노출할 수 있으며, 동일한 데이터와 컨텍스트 엔지니어링 로직을 여러 통합 환경에서 재사용할 수 있습니다.

Agent Builder는 유연하고 개방적인 개발을 지원하며, 널리 사용되는 에이전트 프레임워크 및 플랫폼과 쉽게 통합되도록 설계되었습니다. 효과적인 에이전트를 제공하려면 이러한 통합이 필수적인 요소가 될 수 있습니다. Arcade.dev의 공동 창립자인 Sam Partee의 말처럼,

"오늘날 에이전트형 시스템이 실패하는 이유는 AI를 도구와 데이터에 연결하는 과정이 복잡하기 때문입니다. Arcade.dev와 연동된 Elastic Agent Builder는 에이전트의 컨텍스트 조회, 추론, 실행 과정을 개발자가 체계적이고 안전하게 관리할 수 있는 방식을 제공하여, 데모 수준의 에이전트를 프로덕션 등급으로 끌어올릴 수 있게 합니다.

Agent Builder는 복잡한 데이터 처리를 위해 Elasticsearch의 확장성을 활용하기도 합니다. LlamaIndex CEO인 Jerry Liu의 말처럼,

"비정형 데이터 소스에서 엔터프라이즈 컨텍스트를 끌어내는 것이 효과적인 에이전트를 구축하는 데 있어 핵심입니다. LlamaIndex의 복잡한 문서 처리 기능과 결합된 Elastic Agent Builder는 핵심 컨텍스트 계층을 강화해, 팀이 데이터를 검색·가공·준비할 수 있도록 지원하며 에이전트가 보다 정확하게 추론하고 더 나은 결과를 제공하도록 합니다.

무엇을 구축할 수 있나요?

Agent Builder는 이미 다양한 사용 사례에 사용되고 있습니다. 아래에는 에이전트 개발을 시작하는 데 참고할 수 있는 몇 가지 예시와 아키텍처가 소개되어 있습니다.

• 인프라 자동화: 지원 업무 상황에서 에이전트는 읽고, 생각하고, 대화하는 데 활용되어 왔지만, 지금까지는 실제로 관리 대상인 인프라에 직접 접근해 제어하지는 못했습니다. Elastic의 엔지니어링 팀은 해커톤의 일환으로 자동화된 인프라 관리를 위한 에이전트를 구축했습니다. 이 에이전트는 애플리케이션 인프라 문제를 적극적으로 조사하고 자동화된 조치를 취합니다. 인프라 로그를 지능적으로 이해한 결과를 바탕으로 워크플로우를 사용하여 설정을 최적화하고, 문제에 대응하며, 리소스를 확장합니다.
• 보안 위협 분석: Elastic Agent Builder, MCP, Elasticsearch를 사용하여 보안 취약점 에이전트가 개발되었습니다. 내부 보안 데이터와 외부 위협 인텔리전스를 연관시켜 위협 분석을 자동화합니다. 이 에이전트는 과거 인시던트 및 설정 정보를 대상으로 시맨틱 검색을 수행하고, 실시간 인터넷 데이터로 결과를 강화한 뒤 LLM 추론을 적용해 환경적 관련성을 평가하고 위험 우선순위를 정하며 실행 가능한 대응 방안을 도출합니다. 참조 아키텍처를 확인하세요.
• 기술 고객 지원: 에이전트는 사례 요약부터 문제 중복 정리와 신규 문제 생성, 고급 기술 분석까지 여러 지원 작업을 처리할 수 있습니다. Agent Builder는 다단계 하이브리드 검색을 통해 가장 관련성 높은 문제와 해결책, 절차만을 찾아내고, 근본 원인 가설과 조치 계획을 수립할 수 있도록 지원합니다. Agent Builder는 복잡한 지원 시스템의 아키텍처를 단순화하고 제공까지 걸리는 시간을 단축할 수 있습니다.
• 제품 및 콘텐츠 탐색: Agent Builder는 대화형 환경에서 복잡한 제품 카탈로그를 공개하는 과정을 간소화하는 동시에, 조직이 자체 비즈니스 로직과 요구 사항을 유연하게 반영할 수 있도록 합니다.
• 직접 구축: 2026년 1월 22일부터 2월 27일까지 진행되는 Agent Builder 해커톤에 참여하세요. 커뮤니티와 협력하여 검색, 워크플로우, 도구, 추론을 통합한 컨텍스트 중심의 다단계 AI 에이전트를 만들고, 현실 세계의 작업을 자동화할 수 있습니다*

지금 바로 맞춤형 에이전트를 구축해 보세요

Elastic Cloud 체험판으로 시작하고, 설명서를 여기에서 확인해 보세요. 기존 고객의 경우, Agent Builder는 Cloud Serverless와 Elastic Cloud Hosted, 자체 관리형의 Enterprise 티어에서 사용할 수 있습니다.

* 해커톤의 전체 약관, 조건, 참가 자격 요건을 확인하려면 여기를 클릭하세요

그 유리 상자를 유리 깨뜨리는 방법 중 하나는 음성 에이전트의 도입입니다. 음성 에이전트는 사람의 음성을 인식하고 컴퓨터로 생성된 오디오를 합성하는 AI 에이전트를 말합니다. 저지연 전사, 빠른 대규모 언어 모델(LLM), 그리고 사람이 말하는 것처럼 들리는 텍스트-음성 변환 모델의 등장으로 이러한 것이 가능해졌습니다.

음성 에이전트가 진정으로 가치 있는 존재가 되려면 비즈니스 데이터에 접근할 수 있어야 합니다. 이 블로그에서는 음성 에이전트가 어떻게 작동하는지 알아보고 LiveKit과 Elastic Agent Builder를 사용하여 가상의 야외 스포츠 장비 상점인 ElasticSport에 음성 에이전트를 구축해 보겠습니다. 음성 에이전트는 문맥을 인식하고 데이터와 함께 작동합니다.

참여 방법

음성 에이전트 분야에는 크게 두 가지 패러다임이 있습니다. 첫 번째는 음성 간 변환(speech-to-speech) 모델을 사용하는 방식이고, 두 번째는 음성-텍스트(speech-to-text) 변환, LLM, 텍스트-음성(text-to-speech) 변환으로 구성된 음성 파이프라인을 사용하는 방식입니다. 음성 간 변환 모델도 나름의 장점이 있지만, 음성 파이프라인은 사용되는 기술과 문맥 관리 방식을 훨씬 더 세밀하게 사용자 맞춤화할 수 있으며, 에이전트의 행동을 제어할 수 있다는 이점이 있습니다. 본문에서는 음성 파이프라인 모델을 중점적으로 다루겠습니다.

주요 구성 요소

전사(음성-텍스트 변환)

전사는 음성 파이프라인의 진입점입니다. 전사 구성 요소는 원시 오디오 프레임을 입력으로 받아 음성을 텍스트로 전사한 후 그 텍스트를 출력합니다. 전사된 텍스트는 사용자의 발화가 끝났음을 감지할 때까지 버퍼에 저장되며, 발화가 종료되는 시점에 LLM 생성이 시작됩니다. 다양한 제3자 제공 업체에서 저지연 전사를 제공합니다. 선택 시 지연 시간과 전사 정확도를 고려하고, 스트리밍 전사를 지원하는지 확인하세요.

제3자 API 예시: AssemblyAI, Deepgram, OpenAI, ElevenLabs

대화 차례 감지

대화 차례 감지는 화자가 말을 마치고 응답 생성을 시작해야 할 시점을 감지하는 파이프라인 구성 요소입니다. 이를 수행하는 일반적인 방법 중 하나는 Silero VAD와 같은 음성 활동 탐지(VAD) 모델을 사용하는 것입니다. VAD는 오디오 에너지 수치를 사용하여 오디오에 음성이 포함되어 있는지와 음성이 종료된 시점을 감지합니다. 그러나 VAD만으로는 일시 중지와 발화 종료의 차이를 식별할 수 없습니다. 이 때문에 중간 잠정 전사(interim transcript) 또는 원시 오디오를 기반으로 화자가 말을 마쳤는지 예측하는 발화 종료 모델과 결합하는 경우가 많습니다.

예시(Hugging Face): livekit/turn-detector, pipecat-ai/smart-turn-v3

에이전트

에이전트는 음성 파이프라인의 핵심입니다. 의도를 파악하고, 적절한 문맥을 수집하고, 텍스트 형식으로 답변을 구성하는 역할을 담당합니다. Elastic Agent Builder는 기본 제공 추론 기능, 도구 라이브러리, 워크플로우 통합을 사용해 기업 내부 데이터를 활용하면서 외부 서비스와 상호 작용할 수 있는 에이전트를 만들 수 있습니다.

LLM(텍스트 간 변환)

Elastic Agent Builder용 LLM을 선택할 때 고려해야 할 주요 특징은 LLM 추론 벤치마크와 첫 번째 토큰 생성 시간(TTFT) 두 가지입니다.

추론 벤치마크는 LLM이 얼마나 정확한 응답을 생성할 수 있는지를 나타냅니다. 고려해야 할 벤치마크는 연속 대화(multiturn) 대화 준수도와 지능 벤치마크를 평가하는 것으로, 각각 MT-Bench와 Humanity's Last Exam 데이터 세트가 있습니다.

TTFT 벤치마크는 모델이 첫 번째 출력 토큰을 얼마나 빠르게 생성하는지 평가합니다. 다른 유형의 지연 벤치마크도 있지만, TTFT는 음성 에이전트에게 특히 중요합니다. 첫 번째 토큰이 수신되자마자 음성 합성을 시작할 수 있기 때문인데, 이는 대화 차례 사이의 지연 시간을 줄여 주어 훨씬 자연스러운 대화 경험을 만들어 줍니다

보통 이 두 가지 요소 중 하나를 선택하면 다른 하나는 어느 정도 포기해야 합니다. 속도가 빠른 모델은 대개 추론 능력이 떨어지는 경향이 있기 때문입니다.

예시(Hugging Face): openai/gpt-oss-20b, openai/gpt-oss-120b

합성(텍스트-음성 변환)

파이프라인의 마지막 부분은 텍스트-음성 변환 모델입니다. 이 구성 요소는 LLM에서 출력된 텍스트를 들을 수 있는 음성으로 변환하는 역할을 합니다. LLM과 마찬가지로 지연 시간은 텍스트-음성 변환 제공 업체를 선택할 때 주의해야 할 특성입니다. 텍스트 음성 변환 지연 시간은 첫 바이트까지의 시간(TTFB)으로 측정됩니다. 이는 첫 번째 오디오 바이트가 수신될 때까지 걸리는 시간을 의미합니다. TTFB가 낮으면 대화 차례 사이의 지연 시간도 줄어듭니다.

예시: ElevenLabs, Cartesia, Rime

음성 파이프라인 구축

Elastic Agent Builder는 여러 가지 수준에서 음성 파이프라인에 통합될 수 있습니다.

1. Agent Builder 도구만 해당: 음성-텍스트 변환 → LLM(Agent Builder 도구 사용) → 텍스트-음성 변환
2. MCP 방식의 Agent Builder: 음성-텍스트 변환 → LLM(MCP를 통해 Agent Builder에 접근) → 텍스트-음성 변환
3. Agent Builder를 핵심으로 사용: 음성-텍스트 변환 → Agent Builder → 텍스트-음성 변환

이 프로젝트에서는 Agent Builder를 핵심 접근 방식으로 선택했습니다. 이러한 접근 방식을 통해 Agent Builder와 워크플로우의 전체 기능을 사용할 수 있습니다. 이 프로젝트는 LiveKit을 사용하여 음성-텍스트 변환, 발화 차례 감지 및 텍스트-음성 변환을 오케스트레이션하고, Agent Builder와 직접 통합되는 맞춤형 LLM 노드를 구현합니다.

Elastic 지원 음성 에이전트

ElasticSport라는 가상의 스포츠 매장에 맞춤형 지원 음성 에이전트를 구축 해 보겠습니다. 고객은 헬프라인에 전화해 제품 추천을 요청하고, 제품 세부 정보를 찾고, 주문 상태를 확인하고, 주문 정보를 문자 메시지로 받을 수 있습니다. 이렇게 하려면 먼저 맞춤형 에이전트를 구성하고 Elasticsearch 쿼리 언어(ES|QL) 쿼리 및 워크플로우를 실행하기 위한 도구를 생성해야 합니다.

에이전트 구성

프롬프트

프롬프트는 에이전트가 어떤 성격을 가져야 하고 어떻게 응답해야 하는지 지시합니다. 중요한 것은, 응답이 오디오로 제대로 합성되고 오해가 발생하더라도 유연하게 해결될 수 있도록 하는 몇 가지 음성별 프롬프트가 있다는 점입니다.

You are a Sales Assistant at ElasticSport, an outdoor sport shop specialized in hiking and winter equipment. 

[Profile]
- name: Iva
- company: ElasticSport
- role: Sales Assistant
- language: en-GB
- description: ElasticSport virtual sales assistant

[Context]
- Ask clarifying questions to understand the context.
- Use available tools to answer the user's question.
- Use the knowledge base to retrieve general information

[Style]
- Be informative and comprehensive.
- Maintain a professional, friendly and polite tone.
- Mimic human behavior and speech patterns.
- Be concise. Do not over explain initially

[Response Guideline]
- Present dates in spelled-out month date format (e.g., January fifteenth, two thousand and twenty-four).
- Avoid the use of unpronounceable punctuation such as bullet points, tables, emojis.
- Respond in plain text, avoid any formatting.
- Spell out numbers as words for more natural-sounding speech.
- Respond in short and concise sentences. Responses should be 1 or 2 sentences long.

[ERROR RECOVERY]
### Misunderstanding Protocol
1. Acknowledge potential misunderstanding
2. Request specific clarification

워크플로우

Twilio의 메시징 API를 통해 SMS를 보내기 위한 작은 워크플로우를 추가해 보겠습니다. 해당 워크플로우는 맞춤형 에이전트에게 하나의 '도구' 형태로 제공되며, 이를 통해 에이전트가 통화 중에 발신자에게 SMS 문자를 보낼 수 있는 사용자 경험을 구현할 수 있습니다. 예를 들어 발신자는 "X 에 대한 자세한 내용을 문자로 보내 줄 수 있나요?"라고 물어볼 수 있습니다.

name: send sms
enabled: true
triggers:
  - type: manual
inputs:
  - name: message
    type: string
    description: The message to send to the phone number.

  - name: phone_number
    type: string
    description: The phone number to send the message to.

consts:
  TWILIO_ACCOUNT: "****"
  BASIC_AUTH: "****"
  FROM_PHONE_NNUMBER: "****"
steps:
  - name: http_step
    type: http
    with:
      url: https://api.twilio.com/2010-04-01/Accounts/{{consts.TWILIO_ACCOUNT}}/Messages.json
      method: POST
      headers:
        Content-Type: application/x-www-form-urlencoded
        Authorization: Basic {{consts.BASIC_AUTH | base64_encode}}
      body: From={{consts.FROM_PHONE_NNUMBER}}&To={{inputs.phone_number}}&Body={{inputs.message}}
      timeout: 30s

ES|QL 도구

다음 도구를 사용하여 에이전트가 실제 데이터를 기반으로 관련 응답을 제공할 수 있습니다. 예시 리포지토리에는 제품, 주문, 지식 기반 데이터 세트로 Kibana를 초기화하는 설정 스크립트가 포함되어 있습니다.

• Product.search

제품 데이터 세트에는 65개의 가상 제품이 포함되어 있습니다. 다음은 예시 문서입니다.

{
      "sku": "ort3M7k",
      "name": "Ortovox Free Rider 26 Backpack",
      "price": 189,
      "currency": "USD",
      "image": "https://via.placeholder.com/150",
      "description": "The Ortovox Free Rider 26 is a technical freeride backpack with a dedicated safety compartment and diagonal ski carry system. Perfect for backcountry missions.\n\nKey Features:\n- 26L capacity\n- Diagonal ski carry system\n- Safety equipment compartment\n- Helmet holder\n- Hydration system compatible",
      "category": "Accessories",
      "subCategory": "Backpacks",
      "brand": "Ortovox",
      "sizes": ["One Size"],
      "colors": ["Black", "Blue", "Orange"],
      "materials": ["Nylon", "Polyester"]
    }

이름과 설명 필드는 semantic_text(으)로 맵핑되어 있어 LLM이 ES|QL을 통해 의미를 검색하여 관련 제품을 검색할 수 있습니다. 하이브리드 검색 쿼리는 두 필드 모두에 걸쳐 의미 일치 작업을 수행하며, 이름 필드 일치에는 부스트를 적용하여 약간 더 높은 가중치를 부여합니다.

쿼리는 먼저 초기 관련성 점수에 따라 순위가 매겨진 상위 20개의 결과를 검색합니다. 이러한 결과는 .rerank-v1-elasticsearch 추론 모델을 사용해 설명 필드를 기반으로 다시 순위가 매겨지고, 최종적으로 가장 관련성 높은 다섯 가지 제품을 선별합니다.

type: ES|QL
toolId: products.search
description: Use this tool to search through the product catalogue by keywords.
query: |
    FROM products
        METADATA _score
      | WHERE
          MATCH(name, ?query, {"boost": 0.6}) OR
            MATCH(description, ?query, {"boost": 0.4})
      | SORT _score DESC
      | LIMIT 20
      | RERANK ?query
            ON description
            WITH {"inference_id": ".rerank-v1-elasticsearch"}
      | LIMIT 5

parameters:
    query: space separated keywords to search for in catalogue

• Knowledgebase.search

지식 기반 데이터 세트에는 다음과 같은 형태의 문서가 포함되어 있으며, 여기서 제목과 내용 필드는 의미 텍스트로 저장됩니다.

{
        id: "8273645",
        createdAt: "2025-11-14",
        title: "International Orders",
        content: `International orders are processed through our international shipping partner. Below are the countries we ship to and average delivery times.
        Germany: 3-5 working days
        France: 3-5 working days
        Italy: 3-5 working days
        Spain: 3-5 working days
        United Kingdom: 3-5 working days
        United States: 3-5 working days
        Canada: 3-5 working days
        Australia: 3-5 working days
        New Zealand: 3-5 working days
        `
}

이 도구는 product.search 도구와 유사한 쿼리를 사용합니다.

type: "ES|QL"
toolId: knowledgebase.search
description: Use this tool to search the knowledgebase.
query: |
  FROM knowledge_base
    METADATA _score
  | WHERE
      MATCH(title, ?query, {"boost": 0.6}) OR
      MATCH(content, ?query, {"boost": 0.4})
  | SORT _score DESC
  | LIMIT 20
  | RERANK ?query
      ON content
      WITH {"inference_id": ".rerank-v1-elasticsearch"}
  | LIMIT 5

parameters:
  query: space separated keywords or natural language phrase to semantically search for in the knowledge base

• Orders.search

마지막으로 추가할 도구는 order_id(으)로 주문을 검색하는 데 사용되는 도구입니다.

type: "ES|QL"
toolId: order.search
description: Use this tool to retrieve an order by its ID.
query: |
  FROM orders
    METADATA _score
  | WHERE order_id == ?order_id
  | SORT _score DESC
  | LIMIT 1

parameters:
  order_id: "the ID of the order"

에이전트를 구성하고 이러한 워크플로우 및 ES|QL 도구를 에이전트에 연결한 후, Kibana 내에서 에이전트를 테스트할 수 있습니다.

ElasticSport 지원 에이전트 구축 외에도, 에이전트와 워크플로우 및 도구를 잠재 고객을 발굴하는 영업 에이전트, 주택 수리 서비스 에이전트, 식당 예약 또는 일정 예약 에이전트 등 다른 사용 사례에 맞춰 설정할 수 있습니다.

마지막으로, 방금 만든 에이전트를 LiveKit, 텍스트-음성 및 음성-텍스트 변환 모델과 연결합니다. 이 블로그 끝에 링크된 리포지토리에는 LiveKit과 함께 사용할 수 있는 맞춤형 Elastic Agent Builder LLM 노드가 포함되어 있습니다. AGENT_ID을(를) 자신의 것으로 바꾸고 Kibana 인스턴스와 연결하기만 하면 됩니다.

시작하기

여기에서 코드를 확인하고 직접 사용해 보세요.

우리는 모두 AI 에이전트의 부상을 목격했습니다. AI는 텍스트를 요약하고, 코드 스니펫을 작성하고, 문서를 기반으로 질문에 답하는 데 탁월합니다. 하지만 DevOps 및 사이트 안정성 엔지니어링(SRE) 담당자에게는 답답한 한계가 있었습니다. 대부분의 에이전트는 콜센터 패러다임에 갇혀 있어 읽고, 생각하고, 채팅할 수는 있지만, 관리해야 할 인프라에 직접 접근하여 조작할 수는 없다는 것입니다.

최근 해커톤 프로젝트에서 당사는 이러한 한계를 뛰어넘기로 결정했습니다.

이에 Augmented Infrastructure를 구축했습니다. 이는 단순히 조언만 제공하는 것이 아니라 실시간 환경을 생성, 배포, 모니터링 및 수정하는 인프라 코파일럿입니다.

문제: 복사, 형식 변경, 붙여 넣기

표준 에이전트는 독립적으로 작동합니다. 앱이 다운되어 회사에 5백만 달러의 손실이 발생하면 표준 에이전트는 문제를 해결하는 방법에 대한 런북을 읽어줄 수 있습니다. 하지만 실제 작업은 여전히 사용자가 직접 해야 합니다. 코드를 복사하고, 환경에 맞게 형식을 변경한 다음, 터미널에 붙여 넣어야 합니다.

Kubernetes에 대해 이야기하는 것과 Kubernetes를 구성하는 것의 차이를 이해하는 에이전트가 필요했습니다.

엔진: Elastic Agent Builder란 무엇입니까?

이를 구축하기 위해 처음부터 모든 것을 새로 시작한 것은 아닙니다. Elastic Agent Builder를 기반으로 구축했습니다. Elastic Agent Builder는 에이전트를 신속하게 개발할 수 있도록 설계된 프레임워크로, 대규모 언어 모델(LLM)(데모에서는 Google Gemini를 사용했습니다)과 Elasticsearch에 저장된 개인 데이터 간의 연결 고리 역할을 합니다.

Agent Builder는 문서나 로그와 같은 내부 데이터를 기반으로 대화형 AI를 구현하는 데 사용할 수 있습니다. 하지만 Agent Builder의 가장 강력한 기능은 도구를 할당할 수 있다는 점입니다. 이러한 도구를 통해 LLM은 채팅 인터페이스를 벗어나 특정 작업을 수행할 수 있습니다. 이 기능을 최대한 활용하면 Agent Builder를 강력한 자동화 도구로 탈바꿈시킬 수 있다는 사실을 깨달았습니다.

작동시키기: 첫 번째 버전 구축

프로젝트를 시작할 때 에이전트가 외부 세계를 변화시킬 수 있도록 만들고 싶었습니다. 그래서 이런 아이디어를 떠올렸습니다. (에이전트가 호스트에서 생각할 수 있는 모든 명령을 실행하는) '실행기' 소프트웨어를 구축하면 어떨까? 그리고 만약 실행기, Elastic Agent Builder, 그리고 사용자가 3자 호출을 하면 어떨까?

먼저 Augmented Infrastructure 실행기라는 Python 프로젝트를 구축했는데, 이는 기본적으로 Elastic Agent Builder 대화 API를 매초마다 쿼리하고 당사가 만든 특수 구문을 확인하는 while(true) 루프였습니다.

{
	"tool_name": "my_tool",
       "tool_arguments": "\{stringified json arguments\}"
}

그런 다음 새로운 도구 호출 구문에 대해 알려주도록 프롬프트를 업데이트했습니다. Bill은 Python으로 모델 컨텍스트 프로토콜(MCP) 서버를 구축하는 데 가장 많이 사용되는 프레임워크인 FastMCP의 유지 관리자입니다. Bill은 FastMCP 클라이언트와 이 새로운 실행기 소프트웨어를 사용하여 MCP 서버를 마운트하고 실행기에서 해당 도구를 사용할 수 있도록 하는 작업을 시작했습니다. 에이전트가 이를 확인하면 도구 호출을 실행하고 그러면 마치 사용자가 결과를 보낸 것처럼 결과가 대화창에 다시 POST(으)로 전송됩니다. 이렇게 하면 LLM이 결과에 응답하게 되고, 그렇게 진행이 가능해집니다!

매우 훌륭했지만 다음과 같이 두 가지 주요 문제가 있었습니다.

1. 에이전트가 이 모든 JSON을 사용자와의 대화로 바로 내보냅니다.
2. 대화 API를 통해 메시지를 볼 수 있는 가장 빠른 시점이 대화 라운드가 완료된 시점(즉, LLM이 응답한 시점)입니다.

그래서 이를 백그라운드로 옮기는 방법을 파악하기 위해 노력했습니다.

그다음, 에이전트에 call_external_tool(이)라는 도구를 제공하고 두 개의 인수를 전달하도록 변경했습니다. 하나는 tool_name이고 다른 하나는 문자열화된 JSON 도구 인수입니다. 이 외부 도구 호출은 아무것도 반환하지 않지만, 중요한 것은 대화 API에 대한 GET 요청에서 확인할 수 있다는 점입니다. 그런 다음 실행기에 Elasticsearch에 직접 문서를 작성할 수 있는 권한을 부여했고, Elastic Agent Builder 에이전트는 필요에 따라 해당 문서를 검색할 수 있습니다. 에이전트는 항상 사용자 메시지에 응답하여 작동하므로, 에이전트가 결과를 찾고 처리를 계속할 수 있도록 사용자 메시지로 에이전트를 시작해야 합니다. 그래서 다음과 같이 에이전트가 채팅에 간단한 메시지를 삽입하여 대화를 재개하도록 했습니다.

이제 외부 도구 호출이 가능해졌습니다. 하지만 위에서 언급한 두 번째 문제 때문에 마지막 시작 단계를 없애야 했습니다. 그렇지 않으면 외부 도구를 호출할 때마다 결과를 얻기 위해 전체 대화 라운드을 거쳐야 했기 때문입니다.

효율적으로 만들기: 워크플로우 소개

Agent Builder 에이전트는 Elasticsearch 쿼리 언어(ES|QL) 및 인덱스 검색 도구 호출 외에도 Elastic 워크플로우 기반 도구를 호출할 수 있습니다. Elastic 워크플로우는 임의의 작업 순서와 로직을 실행할 수 있는 유연하고 관리하기 쉬운 방법을 제공합니다. 본 예시에서는 워크플로우가 외부 도구에 대한 Elasticsearch 요청을 저장하고 결과를 폴링할 ID를 반환하기만 하면 됩니다. 따라서 다음과 같은 간단한 워크플로우 정의가 생성됩니다.

name: ai-tool-call
enabled: true
triggers:
  - type: manual
inputs:
  - name: runner_id
    type: string
  - name: tool_calls
    type: string

steps:
  - name: store_request
    type: elasticsearch.create
    with:
      index: distributed-tool-requests
      id: "{{inputs.runner_id}}_{{ execution.id }}"
      document:
        request_id: "{{ execution.id }}"
        runner_id: "{{inputs.runner_id}}"
        tool_call: "{{inputs.tool_calls}}"
        status: "unhandled"

  - name: output_result
    type: console
    with:
      message: "Called tool, with execution id: {{ execution.id }}. Use this ID to poll the results."

이를 통해 도구 호출 요청이 대화에 기록되는 것에 의존하는 대신, 실행기는 새로운 외부 도구 요청에 대해 Elasticsearch distributed-tool-requests 인덱스를 폴링하고 제공된 execution.id을(를) 사용하여 결과를 다른 Elasticsearch 인덱스에 보고할 수 있습니다.

이는 다음과 같이 위에서 언급한 두 가지 주요 문제를 해결합니다.

1. 대화 기록이 더 이상 외부 도구 호출에 위한 페이로드로 인해 복잡해지지 않습니다.
2. 실행기는 대화 기록 대신 Elasticsearch 인덱스를 폴링하므로, 외부 도구 요청이 표시되기 위해 대화 라운드가 완료될 때까지 차단되지 않습니다.

두 번째는 외부 도구 호출 처리가 대화 라운드가 완료된 시점이 아니라 에이전트의 사고 단계 내에서 시작된다는 큰 장점이 있습니다. 이를 통해 시스템 프롬프트에서 LLM에 외부 도구 결과가 나올 때까지 지속적으로 폴링하도록 지시할 수 있으며, 시작 메시지를 표시할 필요가 없습니다. 전반적으로 이러한 방식은 대화 흐름을 더욱 자연스럽게 만들어 줍니다. LLM은 단일 대화 라운드 내에서 여러 외부 도구 요청을 처리할 수 있으므로(도구 요청당 별도의 대화 라운드가 필요하지 않음), 더 복잡한 사용자 요청을 한 번에 처리할 수 있습니다.

한곳에 모으기

LLM과 서버 랙 간의 격차를 해소하기 위해 다음과 같이 Agent Builder의 도구 기능을 사용하여 특정 아키텍처를 개발했습니다.

1. Augmented Infrastructure 실행기: 대상 환경(서버, Kubernetes 클러스터, 클라우드 계정) 내부에 경량 실행기를 배포했습니다. 이러한 실행기는 각 실행기만 접근 가능한 보안 엔드포인트와 보안 정보를 사용하여 Elastic에 직접 연결됩니다.
2. ES|QL 검색: 코파일럿은 Elastic의 ES|QL을 사용하여 하이브리드 검색을 수행합니다. 단순히 지식을 검색하는 것이 아니라 기능을 검색합니다. 연결된 실행기에 쿼리하여 사용 가능한 도구(예: list_ec2_instances, install_helm_chart)를 확인합니다.
3. 워크플로우 실행: 에이전트가 작업 과정을 결정하면 구조화된 워크플로우를 생성합니다.
4. 피드백 루프: 실행기는 로컬에서 명령을 실행하고 그 결과를 다시 Elasticsearch에 보고합니다. 코파일럿은 인덱스에서 결과를 읽고 다음 단계를 결정합니다.

데모: 장애에서 통합 가시성으로

이 동영상에서는 이 아키텍처의 강력한 성능을 보여주는 두 가지 서로 다른 시나리오를 소개했습니다.

시나리오 1: DevOps 지원

Kubernetes 클러스터의 사각지대 때문에 5백만 달러 규모의 장애가 발생하여 패닉 상태에 빠진 사용자의 이야기로 시작했습니다.

• 요청: "이런 일이 다시 발생하지 않도록 하려면 어떻게 해야 하나요?"
• 작업: 에이전트는 단순히 튜토리얼만 제공하지 않았습니다. 클러스터 식별, 필요한 네임스페이스 생성, Kubernetes 보안 정보 생성, OpenTelemetry Operator 설치, 실시간 APM 대시보드에 대한 링크 즉시 제공을 수행했습니다.
• 결과: 사용자가 단 한 줄의 YAML도 작성하지 않고도 완전한 Kubernetes 통합 가시성과 애플리케이션 인사이트를 얻을 수 있습니다.

시나리오 2: 보안 인계

인프라 보안의 기본 원칙은 보이지 않는 것은 보호할 수 없다는 것입니다. DevOps 복구 작업을 수행하는 동안 에이전트는 환경의 보안을 개선할 기회를 포착합니다.

이전 Elastic Observability 관련 조사에서 발생한 경보를 통해 보안 담당자가 인프라와 직접 소통하는 방법을 시연합니다. 첫째, 클라우드 환경의 자산과 리소스를 열거하고, 둘째, 환경 보안을 보장하는 데 필요한 도구를 배포하는 방법을 보여줍니다.

• 탐색: 코파일럿은 보안 담당자를 위해 AWS 리소스를 열거하고 중요한 문제점을 발견했습니다. 해당 문제점은 엔드포인트 보호가 누락된 공용 엔드포인트가 있는 Amazon Elastic Compute Cloud(EC2) 인스턴스와 Amazon Elastic Kubernetes Service(EKS) 클러스터입니다.
• 조치: 간단한 승인으로 코파일럿은 Elastic Security 확장 탐지 및 응답(XDR), 클라우드 탐지 및 응답(CDR)을 취약한 자산에 배포하여 환경을 실시간으로 보호했습니다.
• 결과: 완벽한 런타임 보안을 통해 배포된 AWS 자산 및 리소스를 보호합니다.

미래: 모든 것이 증강되는 세상

이 프로젝트는 Elastic Agent Builder가 분산 운영의 핵심 역할을 할 수 있음을 입증합니다. 인프라에만 국한되지 않고, 실행기 기술은 다음과 같은 분야에서도 활용될 수 있습니다.

• 증강 합성: 글로벌 실행기 전반의 TLS 오류 진단.
• 증강 개발: 풀 리퀘스트 생성 및 프론트엔드 서비스에서 CAPTCHA 구현.
• 증강 운영: 장애 발생 시 DNS 리졸버 자동 재구성.

직접 사용해 보기

AI의 미래가 단순히 채팅 지원에 그치는 것이 아니라, Augmented Infrastructure에 관한 것이라고 생각합니다. 즉, 고객과 함께 배포, 수정, 관찰, 보호할 수 있는 파트너를 확보하는 것입니다.

지금 바로 코드를 확인하고 분산 실행기(GitHub)와 Elastic Agent Builder를 Elastic Cloud Serverless에서 직접 사용해 보세요!

• Elastic Cloud에서 서버리스 프로젝트를 생성하세요.
• 실행기에 코드를 배포하세요.
• 실행기를 설정하세요.
• mcp.json을 구성하세요.
• 실행기를 시작하면 에이전트와 그 도구가 자동으로 생성됩니다.
• 분산 실행기에 대한 추론, 계획 및 실행을 수행할 수 있는 에이전트와 채팅하세요!

팀: 알렉스, 빌, 길, 그레이엄, 노리

이것이 중요한 이유

대부분의 일반적인 분석 워크플로우는 결국 데이터를 그룹화하는 작업으로 귀결됩니다. 호스팅당 평균 바이트 계산, 사용자당 이벤트 계산 또는 다양한 차원에 걸친 메트릭 집계 등의 작업을 수행하더라도 핵심 작업은 동일합니다. 키를 그룹에 맵핑하고 실행 중인 집계를 업데이트하는 것입니다.

작은 규모에서는 거의 모든 합리적인 해시 테이블이 잘 작동합니다. 대규모 환경(수억 건의 문서와 수백만 개의 개별 그룹)에서는 아주 작은 세부 사항들이 중요해지기 시작합니다. 로드 팩터, 탐색 전략, 메모리 레이아웃 및 캐시 동작이 선형적인 성능 향상을 이뤄내느냐, 혹은 캐시 미스의 장벽에 가로막히느냐를 결정짓는 차이를 만듭니다.

Elasticsearch는 수년간 이러한 워크로드를 지원해 왔지만, 핵심 알고리즘을 현대화할 수 있는 기회를 항상 모색하고 있습니다. 따라서 스위스 테이블에서 영감을 받은 새로운 접근 방식을 평가하고 이를 ES|QL의 통계 계산 방식에 적용했습니다.

스위스 테이블의 본질은 무엇인가요?

스위스 테이블은 Google의 SwissTable로 대중화되고 나중에 Abseil 및 기타 라이브러리에서 채택된 현대적인 해시 테이블의 한 계열입니다.

기존의 해시 테이블은 포인터를 쫓아가거나 키를 로드하는 데 많은 시간을 소비하지만, 그 결과가 일치하지 않는 경우가 많습니다. 스위스 테이블의 주요 특징은 키와 값과는 별도로 저장되는 제어 바이트라는 작은 캐시 상주 배열 구조를 사용하여 대부분의 탐색을 거부함으로써 메모리 트래픽을 획기적으로 줄일 수 있다는 점입니다.

각 제어 바이트는 하나의 슬롯을 나타내며, 저희의 경우에는 두 가지 정보를 인코딩합니다. 바로 해당 슬롯이 비어 있는지 여부와 해시값에서 추출한 짧은 지문입니다. 이러한 제어 바이트는 일반적으로 16개의 그룹으로 메모리에 연속적으로 배치되어 단일 명령, 다중 데이터(SIMD) 처리에 적합합니다.

스위스 테이블은 한 번에 하나의 슬롯을 탐색하는 대신 벡터 명령어를 사용하여 전체 제어 바이트 블록을 스캔합니다. CPU는 단 한 번의 연산으로 새로 들어온 키의 지문을 16개의 슬롯과 비교하고 비어 있는 항목들을 걸러냅니다. 이 빠른 경로에서 살아남은 소수의 후보만 실제 키를 로드하고 비교해야 합니다.

이 설계는 약간의 추가 메타데이터를 사용하는 대신, 훨씬 뛰어난 캐시 지역성을 확보하고 무작위 로드 횟수를 획기적으로 줄입니다. 테이블이 커지고 탐색 체인이 길어질수록 이러한 속성의 가치는 점점 더 중요해집니다.

핵심에 자리잡은 SIMD

이 모든 것의 진정한 주인공은 SIMD입니다.

제어 바이트는 단순히 컴팩트할 뿐만 아니라 벡터 명령어로 처리되도록 명시적으로 설계되었습니다. 단일 SIMD 비교를 통해 한 번에 16개의 지문을 확인할 수 있어, 일반적으로 루프로 처리되는 작업을 몇 가지 광범위한 작업으로 전환할 수 있습니다. 그 예는 다음과 같습니다.

실제로 이는 다음과 같은 의미를 지닙니다.

• 분기 명령 감소.
• 탐색 체인 단축.
• 키 및 값 메모리로부터의 데이터 로드 횟수 감소.
• CPU 실행 유닛의 활용도 대폭 향상.

대부분의 조회 작업은 제어 바이트 스캔 단계에서 마무리됩니다. 다음 단계로 넘어가는 경우, 남은 작업은 매우 집중적이며 예측 가능합니다. 최신 CPU가 잘 처리하는 워크로드는 바로 이런 종류의 워크로드입니다.

SIMD의 작동 원리 살펴보기

애플리케이션의 내부 작동 원리를 살펴보고 싶은 독자를 위해, 테이블에 새 키를 삽입할 때 어떤 일이 일어나는지 알려드리겠습니다. 128비트 벡터를 사용하는 파나마 벡터 API를 활용하여 16개의 제어 바이트를 병렬로 처리합니다.

다음 스니펫은 Intel Rocket Lake에서 AVX-512로 생성된 코드를 보여 줍니다. 명령어는 해당 환경을 반영하지만, 설계는 AVX-512에 의존하지 않습니다. 동일한 고수준 벡터 연산은 동등한 명령어(예: AVX2, SSE 또는 NEON)를 사용하여 다른 플랫폼에서도 실행됩니다.

; Load 16 control bytes from the control block
vmovdqu xmm0, XMMWORD PTR [r9+r10*1+0x10]

; Broadcast the 7-bit fingerprint of the new key across the vector
vpbroadcastb xmm1, r11d

; Compare all 16 control bytes to the new fingerprint
vpcmpeqb k7, xmm0, xmm1
kmovq rbx, k7

; Check if any matches were found
test rbx, rbx
jne 

각 명령어는 삽입 과정에서 명확한 역할을 수행합니다.

• vmovdqu: 128비트 xmm0 레지스터에 연속된 16개의 제어 바이트를 로드합니다.
• vpbroadcastb새로운 키의 7비트 지문을 xmm1 레지스터의 모든 레인에 복제합니다.
• vpcmpeqb: 각 제어 바이트를 브로드캐스트된 지문과 비교하여 일치할 가능성이 있는 마스크를 생성합니다.
• kmovq + test: 마스크를 범용 레지스터로 이동하고 일치하는 항목이 있는지 빠르게 확인합니다.

벤치마킹 결과에 따르면 더 넓은 레지스터를 사용하여 32바이트 또는 64바이트로 확장해도 측정 가능한 성능 이점을 얻을 수 없었기 때문에, 최종적으로 한 번에 16개의 제어 바이트로 구성된 프로빙 그룹을 사용하기로 결정했습니다.

ES|QL과의 통합

Elasticsearch에서 스위스식 해싱을 채택한 것은 단순히 기존 방식을 대체하는 것이 아니었습니다. ES|QL은 메모리 회계, 안정성, 및 나머지 연산 엔진과의 통합 측면에서 매우 엄격한 요구 사항을 가지고 있습니다.

새로운 해시 테이블을 페이지 리사이클러 및 서킷 브레이커 회계 기능을 포함한 Elasticsearch의 메모리 관리 기능과 긴밀하게 통합하여 할당이 가시적이고 제한된 범위 내에서 이루어지도록 했습니다. Elasticsearch의 집계는 밀집된 형태로 저장되고 그룹 ID로 색인되어 메모리 레이아웃을 컴팩트하게, 반복 작업 속도를 빠르게 유지할 뿐만 아니라 임의 접근을 허용함으로써 특정 성능 최적화를 가능하게 합니다.

가변 길이 바이트 키의 경우, 그룹 ID와 함께 전체 해시를 캐시합니다. 이렇게 하면 탐색 과정에서 비용이 많이 드는 해시 코드를 다시 계산하지 않아도 되고, 관련 메타데이터를 서로 가깝게 유지하여 캐시 로컬리티를 개선할 수 있습니다. 리해싱 시에 실제 값을 검사할 필요 없이, 캐싱된 해시 값과 제어 바이트에만 의존하여 처리할 수 있으므로 리사이징 비용을 낮게 유지할 수 있습니다.

구현에서 한 가지 중요한 단순화 포인트는 항목을 절대 삭제하지 않는다는 점입니다. 이를 통해 툼스톤(이전에 점유했던 슬롯을 식별하는 마커)이 필요 없으며, 빈 슬롯을 완전히 비어 있는 상태로 유지할 수 있게 되었습니다. 이는 탐색 동작을 더욱 개선하고 제어 바이트 스캔을 효율적으로 유지합니다.

그 결과, Elasticsearch의 실행 모델에 자연스럽게 녹아들면서도 스위스 테이블만의 매력적인 성능 특성을 유지하는 설계가 탄생했습니다.

성능은 어떻습니까?

작은 카디널리티에서 스위스 테이블은 기존 구현과 거의 동등한 성능을 발휘합니다. 이는 예상된 결과입니다. 테이블의 크기가 작을 때는 캐시 효과의 영향이 적고, 최적화할 만한 탐색 과정이 거의 없기 때문입니다.

카디널리티가 증가함에 따라 상황은 급격히 달라집니다.

위의 히트맵은 1,000개에서 최대 10,000,000개 그룹에 이르는 카디널리티 범위에 걸쳐, 다양한 키 크기(8, 32, 64, 128바이트)별 시간 개선 지수를 보여 줍니다. 카디널리티가 증가함에 따라 개선 지수는 꾸준히 증가하며, 균등 분포의 경우 최대 2~3배에 달합니다.

이러한 추세는 설계 단계에서 예측한 바와 정확히 일치합니다. 기존의 해시 테이블은 카디널리티가 높아질수록 탐색 체인이 길어지지만, 스위스식 탐색은 대부분의 조회를 SIMD 연산에 최적화된 제어 바이트 블록 내에서 해결합니다.

캐시 동작이 알려 주는 이야기

속도 향상이 가능했 이유를 더 잘 이해하기 위해, 동일한 JMH benchmarks를(을) Linux perf 환경에서 실행하여 캐시 및 TLB 통계를 캡처했습니다.

원본 구현과 비교할 때 스위스 버전은 전반적으로 약 60% 적은 캐시 참조를 수행합니다. 최종 레벨 캐시 로드가 4배 이상 감소하고, LLC 로드 미스는 6배 이상 감소합니다. LLC 미스는 보통 메인 메모리 접근으로 곧장 이어지기 때문에, 이러한 감소 만으로도 전체 성능 향상의 상당 부분을 설명할 수 있습니다.

CPU와 더 가까울수록 L1 데이터 캐시 미스가 감소하고, 데이터 TLB 미스는 거의 6배나 줄어어, 공간 지역성이 더 치밀해지고 메모리 접근 패턴이 더 예측 가능해졌음을 의미합니다.

이것이 바로 SIMD 친화적인 제어 바이트가 가져다주는 실질적인 이득입니다. 메모리에 흩어져 있는 키와 값을 반복해서 로드하는 대신, 대부분의 탐색 과정을 캐시에 상주하는 컴팩트한 구조를 스캔하여 해결합니다. 메모리 접근 횟수가 줄어들면 미스가 줄고, 미스가 적을수록 쿼리가 더 빨라집니다.

결론

스위스식 해시 테이블 설계를 채택하고 SIMD 친화적인 탐색을 적극적으로 활용함으로써, 카디널리티가 높은 ES|QL 통계 워크로드에서 2~3배의 속도 향상과 더불어 더욱 안정적이고 예측 가능한 성능을 달성했습니다.

이 연구는 최신 CPU 인식 데이터 구조가 해시 테이블과 같이 이미 잘 알려진 문제에서도 상당한 성능 향상을 가져올 수 있음을 보여줍니다. 여기에는 추가적인 기본 유형 특수화 및 조인과 같은 다른 고카디널리티 경로에서의 사용 등 탐구할 여지가 더 많습니다. 이 모든 것은 Elasticsearch 내부를 지속적으로 현대화하기 위해 광범위하세 진행 중인 노력의 일부일 뿐입니다.

자세한 내용이 궁금하시거나 작업 과정을 살펴보고 싶으시다면, 이 풀 리퀘스트 및 메타 이슈 추적 진행 상황을 Github에서 확인하세요.

해싱을 즐기십시오!

결국 컨텍스트의 모든 요소가 AI의 응답에 영향을 미칩니다. 쓰레기를 넣으면 쓰레기가 나온다(Garbage in, garbage out)는 말이 딱 들어맞습니다.

이 글에서는 AI 에이전트에 단기 메모리와 장기 메모리가 어떤 의미를 갖는지 설명합니다. 특히 다음과 같은 내용을 다룹니다.

• 단기 메모리와 장기 메모리의 차이
• Elasticsearch와 같은 벡터 데이터베이스를 사용하는 Retrieval-Augmented Generation(RAG) 기술과의 관계 및 신중한 메모리 관리가 필요한 이유
• 컨텍스트 오버플로 및 컨텍스트 오염 등 메모리 관리 소홀의 위험성
• 컨텍스트 가지치기, 요약, 관련 정보만 검색 등 에이전트의 메모리를 유용하면서도 안전하게 유지하는 모범 사례
• Elasticsearch를 사용하여 에이전트가 혼동 없이 협업할 수 있도록 멀티 에이전트 시스템에서 메모리를 공유 및 전파하는 방법

AI 에이전트의 단기 메모리와 장기 메모리 비교

AI 에이전트의 단기 메모리는 일반적으로 즉각적인 대화 컨텍스트 또는 상태, 즉 현재 채팅 기록이나 활성 세션의 최근 메시지를 의미합니다. 여기에는 사용자의 최근 쿼리와 최근 주고받은 대화가 포함됩니다. 이는 사람이 대화 중에 기억하는 정보와 매우 유사합니다.

AI 프레임워크는 종종 이러한 임시 메모리를 에이전트 상태의 일부로 유지합니다(예: LangGraph의 이 예시처럼 체크포인터를 사용하여 대화 상태를 저장하는 방식). 단기 메모리는 세션 범위로 제한됩니다. 즉, 단일 대화 또는 작업 내에 존재하며 해당 세션이 종료되면 명시적으로 다른 곳에 저장하지 않는 한 재설정되거나 지워집니다. 세션에 종속된 단기 메모리의 예로는 ChatGPT에서 제공하는 임시 채팅 기능을 들 수 있습니다.

반면 장기 메모리는 여러 대화나 세션에 걸쳐 지속되는 정보를 말합니다. 이는 에이전트가 시간이 지남에 따라 보유하게 되는 지식, 이전에 학습한 사실, 사용자 선호도 또는 영구적으로 기억하도록 지시한 모든 데이터를 말합니다.

장기 메모리는 보통 즉각적인 컨텍스트 윈도우 밖에 있는 파일이나 벡터 데이터베이스와 같은 외부 소스에서 저장하고 가져오는 방식으로 구현됩니다. 단기 채팅 기록과 달리 장기 메모리는 모든 프롬프트에 자동으로 포함되지 않습니다. 대신 주어진 시나리오에 따라 에이전트가 관련 도구가 호출될 때 이를 불러오거나 검색해야 합니다. 실제로 장기 메모리에는 사용자의 프로필 정보, 에이전트가 작성한 이전 답변이나 분석, 에이전트가 쿼리할 수 있는 지식 기반 등이 포함될 수 있습니다.

예를 들어 여행 플래너 에이전트가 있다면 단기 메모리는 현재 여행 문의(날짜, 목적지, 예산) 및 해당 채팅에서의 후속 질문의 세부 사항을 포함할 것입니다. 반면에 장기 메모리는 사용자의 일반적인 여행 선호도, 과거 여정 및 이전 세션에서 공유된 기타 사실을 저장할 수 있습니다. 사용자가 나중에 다시 방문했을 때, 에이전트는 이러한 장기 데이터 저장소(예: 사용자는 해변과 산을 좋아하고, 평균 예산은 10만 루피이며, 방문하고 싶은 버킷리스트가 있고, 어린이 친화적인 명소보다는 역사와 문화 체험을 선호함)를 활용하여 매번 사용자에게 다시 묻지 않고 맞춤형 서비스를 제공할 수 있습니다.

단기 메모리(채팅 기록)는 즉각적인 컨텍스트와 연속성을 제공하는 반면, 장기 메모리는 에이전트가 필요할 때 활용할 수 있는 더 넓은 컨텍스트를 제공합니다. 대부분의 고급 AI 에이전트 프레임워크는 이 두 가지를 모두 지원합니다. 최근 대화를 추적하여 컨텍스트를 유지관리합니다. 그리고 장기 저장소에서 정보를 조회하거나 해당 저장소에 저장하는 메커니즘을 제공합니다. 단기 메모리를 관리하여 컨텍스트 윈도우 내에서 유지되도록 하고, 장기 메모리를 관리하여 에이전트가 이전 상호작용과 페르소나를 기반으로 답변을 확립할 수 있도록 합니다.

컨텍스트 엔지니어링에서 메모리와 RAG

실제로 AI 에이전트에 유용한 장기 메모리를 부여하는 방법은 무엇일까요?

장기 메모리를 위한 대표적인 접근 방식 중 하나는 시맨틱 메모리로, retrieval-augmented generation(RAG)을 통해 구현되는 경우가 많습니다. 이는 LLM을 Elasticsearch와 같은 외부 지식 저장소 또는 벡터 지원 데이터 저장소와 결합하는 것을 의미합니다. LLM은 프롬프트나 기본 제공 학습에 포함된 정보 이상의 정보가 필요할 때 Elasticsearch를 대상으로 시맨틱 검색을 수행하고 가장 관련성이 높은 결과를 컨텍스트로 프롬프트에 삽입합니다. 이렇게 하면 모델의 유효 컨텍스트에 최근 대화(단기 메모리)뿐만 아니라 즉석에서 가져온 관련 장기 사실도 포함됩니다. 그런 다음 LLM은 자체 추론과 검색된 정보를 기반으로 답변을 구성하여 단기 메모리와 장기 메모리를 효과적으로 결합해 보다 정확하고 컨텍스트에 맞는 응답을 생성합니다.

Elasticsearch를 사용하여 AI 에이전트의 장기 메모리를 구현할 수 있습니다. 다음은 Elasticsearch에서 컨텍스트 정보를 검색하여 장기 메모리에 저장하는 방법에 대한 개략적인 예시입니다.

이렇게 하면 에이전트가 제한된 프롬프트에 모든 것을 저장하는 대신 관련 데이터를 검색하여 '기억'하기 때문에 다른 위험을 초래할 수 있습니다.

Elasticsearch 또는 벡터 저장소와 함께 RAG를 사용하면 다음과 같이 여러 가지 이점이 있습니다.

첫째, 학습 컷오프를 넘어 모델에 대한 지식을 확장합니다. 에이전트는 LLM이 알지 못할 수도 있는 최신 정보 또는 도메인별 데이터를 검색할 수 있습니다. 최근 이벤트나 전문 주제에 대한 질문이 있을 때 유용합니다.

둘째, 요청 시 컨텍스트를 검색하면 환각을 줄이는 데 도움이 됩니다. 특히 LLM은 귀하의 특정 사용 사례에 상대적인 독점적 또는 고도로 전문화된 데이터에 대해 훈련되지 않았기 때문에 환각에 노출될 가능성이 매우 높습니다. 최근 OpenAI 논문(왜 언어 모델이 환각을 일으키는 이유(Why Language Models Hallucinate)에서 강조된 것처럼 LLM이 평가를 통해 추측하거나 새로운 정보를 창조하는 대신, 이 모델은 Elasticsearch의 사실 참조를 통해 근거를 마련할 수 있습니다. 당연히 LLM은 벡터 저장소 내 데이터의 신뢰성에 의존하여 잘못된 정보를 진정으로 방지하고, 관련 데이터는 핵심 관련성 측정에 따라 검색됩니다.

셋째, RAG를 사용하면 에이전트가 프롬프트에 담을 수 있는 것보다 훨씬 더 큰 지식 기반을 활용할 수 있습니다. 긴 연구 논문이나 정책 문서와 같은 전체 문서를 컨텍스트 윈도우에 입력하여 과부하를 초래하거나 관련 없는 정보로 인해 모델의 추론이 컨텍스트 오염될 위험을 감수하는 대신, RAG는 청킹 방식을 사용합니다. 대용량 문서는 의미론적으로 유의미한 더 작은 조각으로 분할되며, 시스템은 쿼리와 가장 관련성이 높은 몇 개의 조각만 검색합니다. 이렇게 하면 모델은 지식이 풍부해 보이기 위한 수백만 개의 토큰으로 이루어진 컨텍스트가 필요하지 않고, 훨씬 더 큰 코퍼스에서 적절한 청크에만 액세스하기만 하면 됩니다.

LLM 컨텍스트 윈도우가 커짐에 따라(일부 모델은 이제 수십만, 심지어 수백만 개의 토큰을 지원함) RAG가 '사라졌는지'에 대한 논쟁이 제기되었다는 점에 주목할 필요가 있습니다. 모든 데이터를 프롬프트에 넣으면 안 되는 이유가 무엇일까요? 만약 여러분도 같은 생각을 하고 있다면, 제 동료인 제프리 렌기포(Jeffrey Rengifo)와 에두아르트 마틴(Eduard Martin)이 쓴 더 긴 컨텍스트 ≠ 더 나은 것: RAG가 여전히 중요한 이유(Longer context ≠ better: Why RAG still matters)라는 훌륭한 글을 참고해 보세요. 이렇게 하면 '쓰레기를 넣으면 쓰레기가 나온다'는 문제를 피할 수 있습니다. LLM은 노이즈를 처리하는 대신 중요한 몇 개의 청크에 집중할 수 있습니다.

즉, Elasticsearch 또는 벡터 저장소를 AI 에이전트 아키텍처에 통합하면 장기적인 메모리를 제공합니다. 에이전트는 지식을 외부 저장소에 저장하고 필요할 때 메모리 컨텍스트로 불러옵니다. 이는 각 사용자 쿼리 후에 에이전트가 Elasticsearch에서 관련 정보를 검색한 다음 LLM을 호출하기 전에 프롬프트에 상위 결과를 추가하는 아키텍처로 구현할 수 있습니다. 응답에 유용한 새로운 정보가 포함되어 있으면 장기 저장소에 다시 저장할 수도 있습니다(학습의 피드백 루프 생성). 이러한 검색 기반 메모리를 사용함으로써 에이전트는 모든 프롬프트에 알고 있는 모든 것을 집어넣을 필요 없이 정보를 유지하고 최신 상태로 유지합니다. 컨텍스트 윈도우가 100만 토큰을 지원한다고 하더라도 마찬가지입니다. 이 기술은 정보 검색과 생성형 AI의 강점을 결합한 컨텍스트 엔지니어링의 초석입니다.

다음은 세션 중 단기 메모리에 대한 LangGraph의 체크포인트 시스템을 사용하여 관리되는 인메모리 대화 상태의 예시입니다. (지원되는 컨텍스트 엔지니어링 앱을 참조하세요.)

# Initialize chat memory (Note: This is in-memory only, not persistent)
memory = MemorySaver()

# Create a LangGraph agent
langgraph_agent = create_react_agent(model=llm, tools=tools, checkpointer=memory)

...
...
# Only process and display checkpoints if verbose mode is enabled
if args.verbose:
    # List all checkpoints that match a given configuration
    checkpoints = memory.list({"configurable": {"thread_id": "1"}})
    # Process the checkpoints
    process_checkpoints(checkpoints)

체크포인트를 저장하는 방법은 다음과 같습니다.

Checkpoint:
Timestamp: 2025-12-30T09:19:41.691087+00:00
Checkpoint ID: 1f0e560a-c2fa-69ec-8001-14ee5373f9cf
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)
Agent:  (Message ID: lc_run--019b6e8e-553f-7b52-8796-a8b1fbb206a4-0)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.350507+00:00
Checkpoint ID: 1f0e560a-b631-6a08-8000-7796d108109a
User: Hi I'm Som, how are you? (Message ID: ad0a8415-5392-4a58-85ad-84154875bbf2)
Agent: Hi Som! I'm doing well, thank you! How about you? (Message ID: 
56d31efb-14e3-4148-806e-24a839799ece)

Checkpoint:
Timestamp: 2025-12-30T09:19:40.349027+00:00
Checkpoint ID: 1f0e560a-b62e-6010-bfff-cbebe1d865f6

장기 메모리의 경우, Elasticsearch에서 시맨틱 검색을 수행하여 체크포인트를 요약하고 색인한 후 벡터 임베딩을 사용하여 관련 이전 대화를 검색하는 방법은 다음과 같습니다.

Functions: 
retrieve_from_elasticsearch() 

# Enhanced Elasticsearch retrieval with rank_window and verbose display
def retrieve_from_elasticsearch(query: str, k: int = 5, rank_window: int = None) -> tuple[List[Dict[str, Any]], str]:
    """
    Retrieve context from Elasticsearch with score-based ranking
    
    Args:
        query: Search query
        k: Number of results to return
        rank_window: Number of candidates to retrieve before ranking (default: args.rank_window)
        
    Returns:
        Tuple of (retrieved_documents, formatted_context_string)
    """
    if not es_client or not es_index_name:
        return [], "Elasticsearch is not available. Cannot search long-term memory."
    
    if rank_window is None:
        rank_window = args.rank_window
    
    try:
        # Check if index exists and has documents
        if not es_client.indices.exists(index=es_index_name):
            return [], "No previous conversations stored in long-term memory yet."
        
        # Get document count
        try:
            doc_count = es_client.count(index=es_index_name)["count"]
            if doc_count == 0:
                return [], "Long-term memory is empty. No previous conversations to search."
        except Exception as e:
            return [], f"Error checking memory: {str(e)}"
        
        # Generate embedding for the query
        try:
            query_embedding = embeddings.embed_query(query)
        except Exception as e:
            return [], f"Error generating embedding: {str(e)}"
        
        # Perform semantic search using kNN with rank_window
        try:
            search_body = {
                "knn": {
                    "field": "vector",
                    "query_vector": query_embedding,
                    "k": k,
                    "num_candidates": rank_window  # Retrieve more candidates, then rank top k
                },
                "_source": ["text", "content", "message_type", "timestamp", "thread_id"],
                "size": k
            }
            
            response = es_client.search(index=es_index_name, body=search_body)
            
            if not response.get("hits") or len(response["hits"]["hits"]) == 0:
                return [], "No relevant previous conversations found in long-term memory."
            
            # Extract documents with scores
            retrieved_docs = []
            for hit in response["hits"]["hits"]:
                source = hit["_source"]
                score = hit["_score"]
                retrieved_docs.append({
                    "content": source.get("content", source.get("text", "")),
                    "message_type": source.get("message_type", "unknown"),
                    "timestamp": source.get("timestamp", "unknown"),
                    "thread_id": source.get("thread_id", "unknown"),
                    "score": score
                })
            
            # Format context string
            context_parts = []
            for i, doc in enumerate(retrieved_docs, 1):
                context_parts.append(doc["content"])
            
            context_string = "\n\n".join(context_parts)
            
            # Verbose display
            if args.verbose:
                rich.print(f"\n[bold yellow]🔍 RETRIEVAL ANALYSIS[/bold yellow]")
                rich.print("="*80)
                rich.print(f"[blue]Query:[/blue] {query}")
                rich.print(f"[blue]Retrieved:[/blue] {len(retrieved_docs)} documents (from {rank_window} candidates)")
                rich.print(f"[blue]Total context length:[/blue] {len(context_string)} characters\n")
                
                for i, doc in enumerate(retrieved_docs, 1):
                    rich.print(f"[cyan]📄 Document {i} | Score: {doc['score']:.4f} | Type: {doc['message_type']}[/cyan]")
                    rich.print(f"[cyan]   Timestamp: {doc['timestamp']} | Thread: {doc['thread_id']}[/cyan]")
                    content_preview = doc['content'][:200] + "..." if len(doc['content']) > 200 else doc['content']
                    rich.print(f"[cyan]   Content: {content_preview}[/cyan]")
                    rich.print("-" * 80)
            
            return retrieved_docs, context_string
            
        except Exception as e:
            return [], f"Error searching memory: {str(e)}"
            
    except Exception as e:
        return [], f"Error accessing long-term memory: {str(e)}"

이제 Elasticsearch에서 LangGraph의 체크포인트를 사용해 단기 메모리와 장기 메모리를 색인하고 가져오는 방법을 알아보았으니, 전체 대화를 색인하고 덤핑하는 것이 왜 위험한지 잠시 시간을 내어 살펴보겠습니다.

컨텍스트 메모리를 관리하지 않을 경우의 위험성

컨텍스트 엔지니어링과 단기 및 장기 메모리에 대해 많이 이야기하고 있으니, 에이전트의 메모리와 컨텍스트를 제대로 관리하지 않으면 어떤 일이 발생하는지 알아보겠습니다.

안타깝게도 AI의 컨텍스트가 지나치게 길어지거나 잘못된 정보를 포함할 경우 여러 가지 문제가 발생할 수 있습니다. 컨텍스트 윈도우가 커질수록 다음과 같은 새로운 오류 유형이 나타납니다.

• 컨텍스트 오염
• 컨텍스트 방해
• 컨텍스트 혼동
• 컨텍스트 충돌
• 컨텍스트 누출 및 지식 충돌
• 환각 및 잘못된 정보

컨텍스트 관리가 부실할 때 발생하는 이러한 문제점과 기타 위험 요소를 자세히 살펴보겠습니다.

컨텍스트 오염

컨텍스트 오염이란 부정확하거나 해로운 정보가 컨텍스트에 유입되어 모델의 후속 출력에 악영향을 미치는 현상을 말합니다. 흔한 예로는 모델이 착각한 내용을 사실로 받아들여 대화 기록에 삽입하는 경우가 있습니다. 그러면 모델은 이후 응답에서 해당 오류를 바탕으로 더 나아가 오류를 증폭시킬 수 있습니다. 반복적인 에이전트 루프에서 잘못된 정보가 공유 컨텍스트(예: 에이전트의 작업 노트 요약)에 들어가면 그 정보는 계속해서 강화될 수 있습니다.

DeepMind 연구진은 Gemini 2.5 보고서(요약본은 여기 참조)에서 장시간 실행된 포켓몬 게임 에이전트에서 다음과 같은 현상을 관찰했습니다. 에이전트가 잘못된 게임 상태를 환각으로 인식하고, 그 환각이 에이전트의 컨텍스트(목표에 대한 메모리)에 기록되면, 에이전트는 불가능한 목표를 중심으로 비합리적인 전략을 세우고 결국 막히게 된다는 것입니다. 다시 말해 오염된 메모리는 에이전트를 잘못된 경로로 무한정 몰아넣을 수 있습니다.

컨텍스트 오염은 의도치 않게(실수로) 발생할 수도 있고, 악의적으로 발생할 수도 있습니다. 예를 들어 프롬프트 주입 공격을 통해 사용자나 제3자가 에이전트가 기억하고 따르는 숨겨진 지침이나 허위 사실을 몰래 삽입하는 경우가 있습니다.

권장 대응책

Wiz, Zerlo, Anthropic의 사례를 바탕으로 컨텍스트 오염 방지 대책은 LLM의 프롬프트, 컨텍스트 윈도우 또는 검색 파이프라인에 잘못되거나 오해의 소지가 있는 정보가 유입되는 것을 막는 데 중점을 둡니다. 주요 단계는 다음과 같습니다.

• 컨텍스트를 지속적으로 확인하세요. 시작 프롬프트뿐만 아니라 대화 내용이나 검색된 텍스트에서 의심스럽거나 유해한 내용이 있는지 모니터링하세요.
• 신뢰할 수 있는 출처를 사용하세요. 신뢰도에 따라 문서에 점수를 매기거나 레이블을 지정하여 시스템이 신뢰할 수 있는 정보를 우선시하고 점수가 낮은 데이터는 무시하도록 하세요.
• 비정상적인 데이터를 탐지하세요. 이상하거나 부적절하거나 조작된 콘텐츠를 감지하는 도구를 사용하여 모델이 사용하기 전에 제거하세요.
• 입력 및 출력을 필터링하세요. 유해하거나 오해의 소지가 있는 텍스트가 시스템에 쉽게 유입되거나 모델에 의해 반복되지 않도록 안전장치를 추가하세요.
• 모델을 정제된 데이터로 업데이트하세요. 시스템을 정기적으로 검증된 정보로 갱신하여 눈에 띄지 않게 침투한 불량 데이터를 차단하세요.
• 사람의 개입을 활용하세요(Human-in-the-loop). 중요한 출력물을 사람이 검토하거나 알려진 신뢰할 수 있는 출처와 비교하도록 하세요.

간단한 사용자 습관도 도움이 됩니다. 긴 채팅을 초기화하고, 관련 정보만 공유하고, 복잡한 작업을 작은 단계로 나누고, 모델 외부에서 깔끔한 메모를 유지관리하는 것 등이 그 예입니다.

이러한 조치를 종합하면 LLM을 컨텍스트 오염으로부터 보호하고 출력의 정확성과 신뢰성을 유지하는 다층적인 방어 체계가 구축됩니다.

여기서 언급한 대응책이 없다면 에이전트는 공격자가 삽입한 지시(예: 이전 지침 또는 사소한 사실 무시)를 기억하여 악의적인 출력을 생성할 수 있습니다.

컨텍스트 방해

컨텍스트 방해는 컨텍스트가 너무 길어져 모델이 학습 중에 습득한 내용을 무시하고 컨텍스트에 과도하게 집중하는 경우를 말합니다. 극단적인 경우, 이는 치명적인 망각과 유사합니다. 즉, 모델이 기본 지식을 사실상 '망각'하고 눈앞에 놓인 정보에 지나치게 집착하게 되는 것입니다. 이전 연구에 따르면 LLM은 프롬프트가 극도로 길 때 종종 집중력을 잃는 것으로 나타났습니다.

예를 들어 Gemini 2.5 에이전트는 100만 토큰 윈도우를 지원했지만, 컨텍스트가 특정 지점(실험에서 10만 토큰 정도)을 넘어서자 새로운 솔루션을 제시하는 대신 과거의 행동을 반복하는 데 집착하기 시작했습니다. 말하자면, 에이전트는 방대한 과거 이력에 갇힌 것입니다. 기본 학습 지식을 활용해 새롭고 참신한 전략을 고안하는 대신, 이전 행동의 긴 로그(컨텍스트)를 계속 살펴보고 이를 모방했습니다.

이는 역효과를 초래합니다. 우리는 모델이 추론을 돕기 위해 관련 컨텍스트를 사용하길 원하지, 모델의 사고 능력을 무시하길 원하지 않습니다. 특히, 방대한 데이터 윈도우를 가진 모델조차도 이러한 컨텍스트 왜곡 현상을 보입니다. 즉, 토큰이 추가될수록 성능이 불균일하게 저하됩니다. 주의력 예산이 있는 것으로 보입니다. 작업 기억이 제한된 인간과 마찬가지로 LLM도 토큰에 집중할 수 있는 용량이 한정되어 있으며, 그 예산이 늘어날수록 정확도와 집중력이 떨어집니다.

이러한 문제를 완화하기 위해 청킹, 적절한 정보 엔지니어링, 정기적인 컨텍스트 요약, 점수화를 통한 응답의 정확성을 측정하는 평가 및 모니터링 기법을 사용하여 컨텍스트 방해를 방지할 수 있습니다.

이러한 방법은 모델이 관련 컨텍스트와 기본 학습에 기반을 두도록 하여 주의가 산만해질 위험을 줄이고 전반적인 추론 품질을 향상합니다.

컨텍스트 혼동

컨텍스트 혼동이란 모델이 컨텍스트에 있는 불필요한 콘텐츠를 사용하여 품질이 낮은 응답을 생성하는 것을 말합니다. 대표적인 예로 에이전트에 사용할 수 있는 많은 도구나 API 정의를 제공하는 경우를 들 수 있습니다. 이러한 도구 중 상당수가 현재 작업과 관련이 없더라도, 모델은 컨텍스트에 있다는 이유만으로 부적절하게 사용하려고 시도할 수 있습니다. 실험 결과, 필요하지 않은 도구나 문서를 더 많이 제공하면 오히려 성능이 저하될 수 있다는 사실이 밝혀졌습니다. 에이전트가 잘못된 함수를 호출하거나 관련 없는 텍스트를 참조하는 등의 오류를 범하기 시작하는 것입니다.

한 사례에서 소형 Llama 3.1 8B 모델은 고려해야 할 도구가 46개 주어졌을 때는 작업에 실패했지만, 19개만 주어졌을 때는 성공했습니다. 컨텍스트 길이가 제한 내에 있었음에도 불구하고, 추가 도구는 혼동을 야기했습니다. 근본적인 문제는 프롬프트에 포함된 모든 정보가 모델에 의해 처리된다는 점입니다. 모델이 어떤 정보를 무시해야 하는지 알지 못하면, 그 정보가 모델의 출력에 원치 않는 영향을 미칠 수 있습니다. 관련 없는 정보가 모델의 주의를 분산시켜 잘못된 방향으로 이끌 수 있습니다(예를 들어 관련 없는 문서로 인해 에이전트가 질문과 다른 답변을 할 수 있습니다). 컨텍스트 혼동은 종종 모델이 관련 없는 컨텍스트를 통합하여 품질이 낮은 응답을 생성하는 형태로 나타납니다. 관련 연구 논문 적을수록 낫다: 엣지 디바이스에서의 LLM 실행을 위한 함수 호출 최적화(Less is More: Optimizing Function Calling for LLM Execution on Edge Devices)를 참조하세요.

이는 더 많은 컨텍스트가 항상 더 나은 것은 아니라는 점을 상기시켜 줍니다. 특히 관련성에 맞게 선별되지 않았다면 더욱 그렇습니다.

컨텍스트 충돌

컨텍스트 충돌은 컨텍스트의 일부가 서로 모순되어 모델의 추론을 방해하는 내부 불일치를 일으킬 때 발생합니다. 에이전트가 충돌하는 여러 정보를 축적하는 경우 충돌이 발생할 수 있습니다.

예를 들어 에이전트가 두 개의 출처에서 데이터를 가져왔다고 가정해 보겠습니다. 하나는 A 항공편이 오후 5시에 출발한다고 하고, 다른 하나는 A 항공편이 오후 6시에 출발한다고 합니다. 두 사실이 모두 컨텍스트에 포함되면, 성능이 떨어지는 모델은 어느 것이 정확한지 알 수 없습니다. 혼란스러워하거나 부정확한 답변 또는 유사하지 않은 답변을 생성할 수 있습니다.

컨텍스트 충돌은 모델이 이전에 시도했던 답변이 나중에 추가된 정보와 함께 컨텍스트에 남아 있는 다중 턴 대화에서도 자주 발생합니다.

Microsoft와 Salesforce의 연구에 따르면 복잡한 쿼리를 여러 번의 챗봇 턴 대화로 나누어 (세부 정보를 점진적으로 추가하여) 답변할 경우, 모든 정보를 한 번에 제공하는 경우에 비해 최종 정확도가 크게 떨어지는 것으로 나타났습니다. 왜 그럴까요? 초기 턴에는 모델의 부분적이거나 부정확한 중간 답변이 포함되어 있고 이러한 답변이 컨텍스트에 남아 있기 때문입니다. 나중에 모델이 모든 정보를 가지고 답변을 시도할 때, 모델의 메모리에는 여전히 이러한 잘못된 답변이 포함되어 있으며, 이는 수정된 정보와 충돌하여 잘못된 방향으로 나아가게 합니다. 본질적으로 대화의 컨텍스트가 스스로 충돌하는 것입니다. 모델은 새로운 정보를 추가한 후에도 적용되지 않는 오래된 컨텍스트(이전 턴의 컨텍스트)를 의도치 않게 사용할 수 있습니다.

에이전트 시스템에서 컨텍스트 충돌은 특히 위험한데, 에이전트가 서로 다른 도구나 하위 에이전트의 출력을 결합할 수 있기 때문입니다. 이러한 출력이 서로 일치하지 않으면 통합된 컨텍스트가 일관성을 잃게 됩니다. 그러면 에이전트는 모순을 해결하려다 오류가 발생하거나 비합리적인 결과를 생성할 수 있습니다. 컨텍스트 충돌을 방지하려면 컨텍스트를 최신 상태로 유지하고 일관성을 보장해야 합니다. 예를 들어 오래된 정보를 삭제하거나 업데이트하고, 일관성 검증을 거치지 않은 소스를 혼합해서 사용하지 않아야 합니다.

컨텍스트 누출 및 지식 충돌

여러 에이전트 또는 사용자가 메모리 저장소를 공유하는 시스템에서는 컨텍스트 간에 정보가 유출될 위험이 있습니다.

예를 들어 적절한 액세스 제어 없이 두 사용자의 데이터 임베딩이 동일한 벡터 데이터베이스에 저장된 경우, 사용자 A의 쿼리에 응답하는 에이전트가 실수로 사용자 B의 메모리 일부를 가져올 수 있습니다. 이러한 컨텍스트 간 누출은 개인 정보를 노출하거나 응답에 혼란을 초래할 수 있습니다.

LLM 애플리케이션을 위한 OWASP Top 10에 따르면 멀티테넌트 벡터 데이터베이스는 이러한 누출을 방지해야 합니다.

LLM08:2025 벡터 및 임베딩 약점에 따르면, 일반적인 위험 중 하나는 컨텍스트 누출입니다.

여러 사용자 또는 애플리케이션이 동일한 벡터 데이터베이스를 공유하는 멀티테넌트 환경에서는 사용자 또는 쿼리 간에 컨텍스트 누출 위험이 있습니다. 데이터 페더레이션 지식 충돌 오류는 여러 소스의 데이터가 서로 모순될 때 발생할 수 있습니다. 또한 LLM이 학습 과정에서 얻은 기존 지식을 검색 증강을 통해 얻은 새로운 데이터로 대체하지 못할 때도 이러한 오류가 발생할 수 있습니다.

또 다른 측면은 LLM이 기본 제공 지식을 메모리의 새로운 정보로 재정의하는 데 어려움을 겪을 수 있다는 것입니다. 모델이 특정 사실에 기반하여 학습되었는데 검색된 컨텍스트가 그와 반대되는 내용을 담고 있다면 모델은 어떤 것을 신뢰해야 할지 혼란스러워할 수 있습니다. 적절한 설계가 없으면 에이전트가 컨텍스트를 혼동하거나 기존 지식을 새로운 증거로 업데이트하지 못하여 오래되거나 부정확한 답변을 내놓을 수 있습니다.

환각 및 잘못된 정보

환각(LLM이 그럴듯하지만, 틀린 정보를 만드는 것)은 긴 설명이 필요 없는 잘 알려진 문제로, 메모리 관리가 제대로 이루어지지 않으면 더욱 심해질 수 있습니다.

에이전트의 메모리에 중요한 사실이 누락된 경우, 모델은 추측으로 그 공백을 채울 수 있으며, 만약 그 추측이 컨텍스트에 들어가게 되면(컨텍스트를 오염시키면서) 오류가 지속됩니다.

OWASP LLM 보안 보고서(LLM09:2025 잘못된 정보)는 잘못된 정보를 핵심 취약점으로 지적합니다. LLM은 확신에 찬 듯 보이지만 조작된 답변을 생성할 수 있으며, 사용자는 이를 과신할 수 있습니다. 장기 메모리가 불량하거나 오래된 에이전트는 메모리가 최신 상태로 유지되지 않으면 작년에는 사실이었지만 지금은 거짓인 정보를 확신에 차서 인용할 수 있습니다.

AI의 출력에 지나치게 의존하는 것(사용자 또는 에이전트 자체가 반복적인 과정에서)은 이러한 문제를 악화시킬 수 있습니다. 메모리에 저장된 정보를 아무도 검증하지 않으면 에이전트는 잘못된 정보를 축적하게 됩니다. 이것이 바로 RAG가 환각을 줄이는 데 자주 사용되는 이유입니다. RAG를 통해 권위 있는 출처를 검색함으로써 모델은 사실을 만들어낼 필요가 없습니다. 하지만 잘못된 문서(예: 잘못된 정보가 포함된 문서)를 검색하거나 초기 환각을 제거하지 않으면 시스템은 해당 잘못된 정보를 전체 작업에 전파할 수 있습니다.

결론적으로 메모리 관리에 실패하면 부정확하고 오해의 소지가 있는 출력으로 이어질 수 있으며, 이는 특히 위험 부담이 큰 경우(예: 금융이나 의료 분야에서 잘못된 조언) 심각한 피해를 초래할 수 있습니다. 에이전트는 컨텍스트에 있는 내용을 무조건 신뢰하는 것이 아니라 메모리 내용을 검증하거나 수정할 수 있는 메커니즘을 갖춰야 합니다.

요약하자면 AI 에이전트에 무한히 긴 메모리를 제공하거나 가능한 모든 것을 컨텍스트에 넣는 것은 성공의 비결이 아닙니다.

LLM 애플리케이션에서의 메모리 관리 모범 사례

위에서 언급한 문제점을 방지하고자 개발자와 연구자는 AI 시스템에서 컨텍스트와 메모리를 관리하는 여러 가지 모범 사례를 고안했습니다. 이러한 사례는 AI의 작업 컨텍스트를 간결하고 관련성 있으며 최신 상태로 유지하는 것을 목표로 합니다. 다음은 주요 전략 몇 가지와 그 효과를 보여주는 예시입니다.

RAG: 타겟팅된 컨텍스트 사용

RAG에 대한 내용은 이전 섹션에서 이미 많이 다루었습니다. 이 부분은 실용적인 핵심 사항을 간략하게 다시 한번 상기시켜 드리는 것입니다.

• 대량 로딩이 아닌 대상 검색을 사용하세요. 전체 문서나 전체 대화 기록을 프롬프트에 입력하는 대신 가장 관련성이 높은 청크만 검색하세요.
• RAG를 적절한 시기에 메모리를 불러오는 기능으로 활용하세요. 모든 정보를 턴 전반에 가져가지 말고, 필요할 때만 컨텍스트를 가져오세요.
• 관련성 인식 검색 전략을 선호하세요. 상위 k개 시멘틱 검색, 상호 순위 융합 또는 도구 구성 필터링과 같은 접근 방식은 노이즈를 줄이고 근거를 개선하는 데 도움이 됩니다.
• 컨텍스트 윈도우가 크다고 해서 RAG의 필요성이 없어지는 것은 아닙니다. 관련성이 높은 두 갱의 단락이 관련성이 낮은 20페이지 분량의 문서보다 거의 항상 더 효과적입니다.

즉, RAG는 더 많은 컨텍스트를 추가하는 것이 아니라 적절한 컨텍스트를 추가하는 것입니다.

도구 구성

도구 구성은 모델에 특정 작업에 실제로 필요한 도구만 제공하는 것을 의미합니다. 이 용어는 게임에서 유래했는데, 상황에 맞는 구성을 선택하는 것과 같습니다. 도구가 너무 많으면 속도가 느려지고, 잘못된 도구는 실패로 이어집니다. 연구 논문 적을수록 낫다(Less is more)에 따르면 LM도 마찬가지로 동작합니다. 도구가 약 30개를 넘어서면 설명이 중복되어 모델이 혼란스러워집니다. 100개를 넘어서면 실패가 거의 확실해집니다. 이는 컨텍스트 윈도우 문제가 아니라 컨텍스트 혼동 문제입니다.

간단하면서도 효과적인 해결책은 RAG-MCP입니다. 모든 도구를 프롬프트에 나열하는 대신, 도구 설명을 벡터 데이터베이스에 저장하고 요청 시 가장 관련성이 높은 도구만 불러옵니다. 실제로 이렇게 하면 도구 구성이 간결하고 집중적으로 유지되고 프롬프트 표시 시간이 크게 단축되며 도구 선택 정확도가 최대 3배까지 향상될 수 있습니다.

소규모 모델일수록 이러한 한계에 더 빨리 부딪힙니다. 연구 결과에 따르면 80억 단위의 모델은 수십 개의 도구를 사용할 때는 제대로 작동하지 않지만, 도구 구성을 줄이면 성공하는 것으로 나타났습니다. 필요한 도구를 추론하여 동적으로 선택하는 방식(때로는 LLM을 먼저 사용하는 방식)은 성능을 44% 향상하면서 전력 소비와 지연 시간도 줄일 수 있습니다. 핵심은 대부분의 에이전트는 몇 개의 도구만 필요하지만, 시스템 규모가 커질수록 도구 구성과 RAG-MCP가 설계에서 가장 중요한 고려 사항이 된다는 것입니다.

컨텍스트 가지치기: 채팅 기록 길이 제한

대화가 여러 차례 이어지면 누적된 채팅 기록이 너무 커져서 컨텍스트 오버플로가 발생하거나 모델에 방해가 될 수 있습니다.

트리밍이란 대화가 길어짐에 따라 중요도가 낮은 부분을 프로그램적으로 제거하거나 축약하는 것을 의미합니다. 간단한 방법으로는 특정 한계에 도달했을 때 가장 오래된 대화 내용을 삭제하고 최근 N개의 메시지만 남기는 것이 있습니다. 더 정교한 가지치기는 관련 없는 곁가지 이야기나 더 이상 필요하지 않은 이전 지시 사항을 제거할 수 있습니다. 목표는 컨텍스트 윈도우를 오래된 정보로 어지럽히지 않고 깔끔하게 유지하는 것입니다.

예를 들어 에이전트가 10턴 전에 하위 문제를 해결했고 그 이후로 넘어갔다면 더 이상 필요하지 않다고 가정하여 해당 기록 부분을 컨텍스트에서 삭제할 수 있습니다(더 이상 필요하지 않다고 가정). 많은 채팅 기반 구현이 이와 같은 방식을 사용합니다. 즉, 최근 메시지의 롤링 윈도우를 유지관리합니다.

트리밍은 대화의 앞부분이 요약되었거나 관련성이 없다고 판단되면 해당 부분을 '잊어버리는' 것처럼 간단하게 할 수 있습니다. 이렇게 하면 컨텍스트 오버플로 오류 위험과 컨텍스트 방해를 줄여 모델이 오래되거나 주제에서 벗어난 콘텐츠에 현혹되지 않도록 할 수 있습니다. 이는 사람이 한 시간짜리 대화의 모든 단어는 기억하지 못하지만 핵심 내용은 기억하는 것과 매우 유사합니다.

컨텍스트 가지치기가 헷갈린다면, 저자 드류 브루니그(Drew Breunig)가 여기서 강조했듯이, 질문 답변을 위한 가볍고(1.75GB), 효율적이며 정확한 컨텍스트 가지치기 도구인 Provence (`naver/provence-reranker-debertav3-v1`) 모델을 사용해 보시면 도움이 될 수 있습니다. 이 모델은 방대한 문서를 특정 쿼리에 가장 관련성이 높은 텍스트만 남기도록 다듬어 줍니다. 특정 간격으로 호출할 수도 있습니다.

컨텍스트 가지치기를 위해 코드에서 `provence-reranker` 모델을 호출하는 방법은 다음과 같습니다.

# Context pruning with Provence
def prune_with_provence(query: str, context: str, threshold: Optional[float] = None) -> str:
    """
    Prune context using Provence reranker model
    
    Args:
        query: User's query/question
        context: Original context to prune
        threshold: Relevance threshold (0-1) for Provence reranker.
                   If None, uses args.pruning_threshold.
                   0.1 = conservative (recommended, no performance drop)
                   0.3-0.5 = moderate to aggressive pruning
    
    Returns:
        Pruned context with only relevant sentences
    """
    if provence_model is None:
        return context
    
    if threshold is None:
        threshold = args.pruning_threshold
    
    try:
        # Use Provence's process method
        provence_output = provence_model.process(
            question=query,
            context=context,
            threshold=threshold,
            always_select_title=False,
            enable_warnings=False
        )
        
        # Extract pruned context from output
        pruned_context = provence_output.get('pruned_context', context)
        reranking_score = provence_output.get('reranking_score', 0.0)
        
        # Log statistics
        original_length = len(context)
        pruned_length = len(pruned_context)
        reduction_pct = ((original_length - pruned_length) / original_length * 100) if original_length > 0 else 0
        
        if args.verbose:
            rich.print(f"[cyan]📊 Pruning stats: {pruned_length}/{original_length} chars ({reduction_pct:.1f}% reduction, threshold={threshold:.2f}, rerank_score={reranking_score:.3f})[/cyan]")
        
        return pruned_context if pruned_context else context
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in Provence pruning: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

문장 관련성 점수 계산에는 Provence reranker 모델(`naver/provence-reranker-debertav3-v1`)을 사용합니다. 임계값 기반 필터링을 통해 관련성 임계값 이상의 문장만 남깁니다. 또한 가지치기가 실패할 경우 원래 컨텍스트으로 되돌아가는 폴백(fallback) 메커니즘을 도입했습니다. 마지막으로 상세 모드에서는 통계 로깅을 통해 감소율을 추적합니다.

컨텍스트 요약: 이전 정보를 완전히 삭제하는 대신 축약

요약은 트리밍의 동반자입니다. 기록이나 지식 베이스가 너무 커지면 위의 코드에서 수행한 것처럼 LLM을 사용하여 중요한 요점에 대한 간략한 요약을 생성하고 앞으로 전체 콘텐츠 대신 이 요약을 사용할 수 있습니다.

예를 들어 AI 어시스턴트가 50턴 대화를 나눴다고 가정해 봅시다. 51턴 대화에서 50턴까지 대화를 한꺼번에 보내는 대신(용량 부족 문제 발생 가능성이 높음), 시스템은 1~40턴까지 대화만 처리하고 모델이 이를 요약하여 단락으로 작성하도록 한 다음, 다음 대화에서는 해당 요약본과 마지막 10턴까지의 대화 내용만 제공할 수 있습니다. 이렇게 하면 모델은 모든 세부 정보를 입력받지 않고도 어떤 내용이 논의되었는지 파악할 수 있습니다. 초기 챗봇 사용자는 "지금까지 나눈 대화를 요약해 줄 수 있나요?"라고 수동으로 질문하고, 요약 내용을 바탕으로 새로운 대화를 이어갔습니다. 이제는 이 작업을 자동화할 수 있습니다. 요약은 컨텍스트 윈도우 공간을 절약할 뿐만 아니라 불필요한 세부 정보를 제거하고 중요한 사실만 유지함으로써 컨텍스트 혼동/방해를 줄일 수 있습니다.

여기서는 OpenAI 모델(다른 LLM 모델도 사용 가능)을 활용하여 모든 관련 정보를 보존하면서 컨텍스트를 축약하고 중복 및 비효율성을 제거하는 방법을 설명합니다.

# Context summarization
def summarize_context(query: str, context: str) -> str:
    """
    Summarize context using LLM to reduce duplication and focus on relevant information
    
    Args:
        query: User's query/question
        context: Context to summarize
        
    Returns:
        Summarized context
    """
    try:
        summary_prompt = f"""You are an expert at summarizing conversation context.

Your task: Analyze the provided conversation context and produce a condensed summary that fully answers or supports the user's specific question.

The summary must:
1. Preserve every fact, detail, and information that directly relates to the question
2. Eliminate redundancy and duplicate information
3. Maintain chronological flow when relevant
4. Focus on information that helps answer: "{query}"

Context to summarize:
{context}

Provide a concise summary that preserves all relevant information:"""

        summary = llm.invoke(summary_prompt).content
        
        if args.verbose:
            original_length = len(context)
            summary_length = len(summary)
            reduction_pct = ((original_length - summary_length) / original_length * 100) if original_length > 0 else 0
            rich.print(f"[cyan]📝 Summarization stats: {summary_length}/{original_length} chars ({reduction_pct:.1f}% reduction)[/cyan]")
        
        return summary
        
    except Exception as e:
        rich.print(f"[yellow]⚠️ Error in context summarization: {str(e)}[/yellow]")
        rich.print(f"[yellow]⚠️ Falling back to original context[/yellow]")
        return context

중요한 것은 컨텍스트가 요약되면 (요약이 정확하다는 가정 하에) 모델이 사소한 세부 사항이나 과거 오류에 압도될 가능성이 줄어든다는 점입니다.

하지만 요약은 신중하게 해야 합니다. 요약이 잘못되면 중요한 세부 사항이 누락되거나 오류가 발생할 수도 있습니다. 요약은 본질적으로 모델에 대한 또 다른 프롬프트("이것을 요약하세요")이기 때문에 뉘앙스가 왜곡되거나 사라질 수 있습니다. 가장 좋은 방법은 점진적으로 요약하고 일부 표준적인 사실은 요약하지 않는 것입니다.

그럼에도 불구하고 이는 매우 유용한 것으로 입증되었습니다. Gemini 에이전트 시나리오에서 약 10만 토큰마다 컨텍스트를 요약하는 것은 모델의 반복적인 경향을 상쇄하는 방법이었습니다. 요약은 대화 또는 데이터의 압축된 메모리 역할을 합니다. 개발자는 에이전트가 대화 기록이나 긴 문서에 대해 주기적으로 요약 함수(소규모 LLM 또는 전용 루틴)를 호출하도록 구현할 수 있습니다. 결과로 생성된 요약은 프롬프트의 원래 내용을 대체합니다. 이 전략은 컨텍스트를 제한적으로 유지하고 정보를 추출하는 데 널리 사용됩니다.

컨텍스트 격리: 가능한 경우 컨텍스트 격리

이는 복잡한 에이전트 시스템이나 다단계 워크플로우에서 더욱 중요합니다. 컨텍스트 세분화의 핵심 아이디어는 큰 작업을 각각 고유한 컨텍스트를 가진 더 작고 독립적인 작업으로 나누는 것입니다. 이렇게 하면 모든 것을 포함하는 하나의 거대한 컨텍스트가 누적되는 것을 방지할 수 있습니다. 각 하위 에이전트 또는 하위 작업은 특정 컨텍스트에 집중하여 문제 일부를 해결하고, 상위 에이전트, 감독자 또는 조정자가 결과를 통합합니다.

Anthropic의 연구 전략은 여러 개의 하위 에이전트를 활용합니다. 각 하위 에이전트는 고유한 컨텍스트 윈도우를 가지고 질문의 서로 다른 측면을 조사하며, 리드 에이전트는 이러한 하위 에이전트가 도출한 결과를 종합적으로 분석합니다. 이러한 병렬적인 모듈식 접근 방식 덕분에 어느 하나의 컨텍스트 윈도우도 과도하게 복잡해지지 않습니다. 또한 관련 없는 정보가 섞일 가능성을 줄이고, 각 스레드는 주제에서 벗어나지 않으며(컨텍스트 혼동 방지), 특정 하위 질문에 답할 때 불필요한 정보를 포함하지 않습니다. 마치 사고 과정 전체가 아닌 결과만 공유하는 별개의 독립적인 사고 스레드를 실행하는 것과 같습니다.

멀티 에이전트 시스템에서는 이러한 접근 방식이 필수적입니다. 에이전트 A가 작업 A를 처리하고 에이전트 B가 작업 B를 처리하는 경우, 정말 필요한 경우가 아니라면 어느 에이전트도 다른 에이전트의 전체 컨텍스트를 소비할 이유가 없습니다. 대신 에이전트는 필요한 정보만 교환할 수 있습니다. 예를 들어 에이전트 A는 감독 에이전트를 통해 에이전트 B에 조사 결과의 통합 요약을 전달할 수 있으며, 각 하위 에이전트는 자체적인 전용 컨텍스트 스레드를 유지관리합니다. 이러한 구성은 사람의 개입이 필요하지 않으며, 최소한의 제어된 컨텍스트 공유 기능을 갖춘 도구를 사용하는 감독 에이전트에 의존합니다.

그럼에도 불구하고 에이전트나 도구가 필요한 컨텍스트 중복을 최소화하면서 작동하도록 시스템을 설계하면 명확성과 성능을 크게 향상할 수 있습니다. 이를 AI를 위한 마이크로서비스라고 생각하면 됩니다. 각 구성 요소는 고유한 컨텍스트를 처리하고, 단일 컨텍스트 대신 제어된 방식으로 구성 요소 간에 메시지를 전달합니다. 이러한 모범 사례는 종종 함께 사용됩니다. 또한 이를 통해 사소한 기록을 트리밍하고 중요한 이전 메시지나 대화를 요약하며, 상세한 로그를 Elasticsearch에 저장하여 장기적인 컨텍스트를 유지하고 필요할 때 관련 정보를 검색할 수 있는 유연성을 확보할 수 있습니다.

앞서 언급했듯이, 핵심 원칙은 컨텍스트는 제한적이고 귀중한 자원이라는 것입니다. 프롬프트의 모든 토큰은 제 역할을 다해야 하며, 출력의 질 향상에 기여해야 합니다. 메모리에 저장된 요소가 제 역할을 하지 못하고 더 나아가 혼동을 야기하는 경우 그 항목을 제거하거나 요약하거나 제외해야 합니다.

개발자로서 이제 코드를 프로그래밍하듯이 컨텍스트를 프로그래밍할 수 있습니다. 어떤 정보를 포함할지, 어떤 형식으로 표현할지, 언제 생략하거나 업데이트할지 결정할 수 있습니다. 이러한 방식을 따르면 LLM 에이전트가 앞서 설명한 오류 모드에 빠지지 않고 작업을 수행하는 데 필요한 컨텍스트를 제공할 수 있습니다. 결과적으로 에이전트는 기억할 정보는 기억하고, 기억할 필요 없는 정보는 잊고, 필요한 정보는 적시에 검색할 수 있게 됩니다.

결론

메모리는 에이전트에 추가하는 것이 아니라 설계하는 것입니다. 단기 메모리는 에이전트의 작업 임시 저장소 역할을 하고, 장기 메모리는 영구적인 지식 저장소 역할을 합니다. RAG는 이 둘을 연결하는 다리 역할을 하며, Elasticsearch와 같은 수동적인 데이터 저장소를 능동적인 재현 메커니즘으로 전환하여 출력을 안정적으로 유지하고 에이전트를 최신 상태로 유지합니다.

하지만 메모리는 양날의 검과도 같습니다. 컨텍스트를 방치하는 순간 오염, 방해, 혼동, 충돌이 발생하고 공유 시스템에서는 데이터 누출까지 일어날 수 있습니다. 그렇기 때문에 가장 중요한 메모리 작업은 '더 많이 저장'하는 것이 아니라 '더 잘 선별'하는 것입니다. 선택적으로 검색하고 공격적으로 정리하며, 신중하게 요약하고 업무에 꼭 필요한 경우가 아니라면 관련 없는 컨텍스트를 섞지 마세요.

실제로 훌륭한 컨텍스트 엔지니어링은 훌륭한 시스템 설계와 유사합니다. 즉, 작고 충분한 컨텍스트, 구성 요소 간의 제어된 인터페이스, 그리고 원시 상태와 모델이 실제로 인식해야 하는 정제된 상태를 명확하게 구분하는 것입니다. 제대로 구현하면 모든 것을 기억하는 에이전트를 만드는 것이 아니라, 적시에 적합한 이유로 적절한 정보를 기억하는 에이전트를 만들 수 있습니다.

AWS에서 실행되는 모든 Elastic Cloud Serverless 프로젝트에 대한 주요 인프라 업그레이드를 완료하여 더 새롭고 빠른 하드웨어로 마이그레이션하였습니다. 해당 변경 사항이 모든 서버리스 프로젝트에 자동으로 적용되었습니다. 이 솔루션은 AWS에서 Elasticsearch, Elastic Observability 및 Elastic Security 서버리스 프로젝트에 더 높은 처리량과 더 낮은 지연 시간을 제공합니다.

개발자를 위한 주요 성능 혜택

새로운 AWS 하드웨어 인프라는 Elastic Cloud Serverless에서 수행하는 모든 작업을 뒷받침하여 애플리케이션의 속도와 반응성에 실질적인 이점을 제공합니다.

쿼리 지연 시간 감소 및 처리량 증가

향상된 하드웨어가 획기적으로 컴퓨팅 리소스의 속도를 높여 검색 쿼리가 그 어느 때보다 빠르게 처리됩니다.

• 검색 및 벡터 검색: 기존의 풀텍스트 쿼리를 실행하든, 생성형 AI 및 검색 증강 생성(RAG) 애플리케이션에 최첨단 벡터 검색을 사용하든, 대기 시간이 현저히 줄어듭니다. 내부 벤치마킹 결과 검색 지연 시간이 평균 35% 감소한 것으로 나타났습니다.
• 더욱 빠른 색인: 데이터 수집 속도가 최적화되어 대용량 데이터와 복잡한 문서를 처리량을 높여 색인할 수 있습니다. 이는 거의 실시간 데이터 가시성이 필요한 애플리케이션에 매우 중요합니다. 내부 벤치마킹 결과, 색인 처리량이 평균 26% 증가했습니다.

부하 상태에서도 일관된 성능

수요에 맞춰 실시간으로 동적으로 자동 확장되도록 설계된 Elastic Cloud Serverless는 작업 부하에 관계없이 대기 시간을 최소화합니다. 이번 하드웨어 업그레이드를 통해 확장이 더욱 향상되고 반응 속도도 빨라졌습니다.

• 급증하는 데이터를 손쉽게 처리: 사용자 트래픽이 갑자기 급증하거나 대규모 배치 데이터 인제스트에 직면하더라도, 새로운 인프라가 검색 및 색인 리소스를 보다 효율적으로 확장하여 낮은 지연 시간을 일관적으로 유지합니다.
• 컴퓨팅-저장 공간 분리 최적화: 서버리스 아키텍처는 컴퓨팅과 저장 공간을 분리하여 워크로드가 독립적으로 확장될 수 있도록 함으로써 최적의 성능과 비용 효율성을 제공합니다. 더 빠른 하드웨어가 컴퓨팅 계층을 향상시켜 분리된 설계의 효율성을 극대화합니다.

작동 원리: 내부 벤치마킹 결과

Elastic 엔지니어링 팀은 AWS 인프라 업그레이드의 영향을 정량화하기 위해 다양한 서버리스 워크로드를 대상으로 포괄적인 내부 벤치마킹을 수행했습니다. 이러한 워크로드는 사용 사례와 관계없이 애플리케이션 전반에서 기대할 수 있는 성능 향상에 대한 실증적 증거를 제공했습니다.

벤치마킹 접근법

개발자 경험과 애플리케이션 반응성에 직접적인 영향을 미치는 주요 지표인 응답 시간(지연 시간)과 검색 및 색인 작업 처리량을 집중적으로 테스트했습니다.

• 테스트를 마친 워크로드: 테스트에는 사용자 대면 애플리케이션에서 흔히 볼 수 있는 동시성이 높은 검색 작업, 복잡한 벡터 검색 쿼리, 통합 가시성 및 보안 사용 사례에 대한 대용량 데이터 수집/색인 등이 포함되었습니다. 그중에서도 테스트 방법론에서 Elastic의 벤치마킹 도구인 Rally에 대해 공개적으로 이용 가능한 데이터 세트를 사용했습니다.
  • wikipedia: 위키피디아 텍스트 콘텐츠의 스냅샷에서 추출된 데이터 세트로, 일반 텍스트 검색 성능을 측정하는 데 사용됩니다.
  • MSMARCO-Passage-Ranking: Microsoft의 Machine Reading Comprehension(MS MARCO)에서 파생된 데이터 세트로, 희소 벡터 필드에서 검색 성능을 측정합니다.
  • OpenAI_Vector: BEIR의 NQ에서 파생된 데이터 세트로, OpenAI의 text-embedding-ada-002 모델이 생성한 임베딩으로 보강되어 조밀한 벡터 필드에서의 검색 성능을 측정하기 위한 것입니다.
• 측정: 구식 인프라와 신규 인프라의 성능을 비교했으며, 최악의 경우인 극한 지연 시간 성능과 초당 작업량을 파악하기 위해 99번째 백분위수(P99)에서의 지연 시간을 측정했습니다. 결과의 일관성을 확보하기 위해 하드웨어 프로필마다 각 트랙을 5회씩 실행했습니다.
• 목표: 목표는 빠른 자동 확장 기간에도 전반적으로 일관되게 더 빠르고 예측 가능한 성능을 제공하는 인프라의 기능을 검증하는 것이었습니다.

성능 데이터 요약

그 결과 효율성과 속도가 크게 향상되었음을 확인할 수 있었습니다. 이러한 이점은 사용자 응답 시간 단축과 운영 비용 절감으로 직결됩니다. 더 적은 컴퓨팅 리소스로 동일한 작업을 완료할 수 있기 때문입니다.

다음 표에는 정량적 개선 사항이 자세히 설명되어 있습니다. 높은 값은 처리량에 더 좋고, 낮은 값은 지연 시간에 더 좋습니다.

벤치마크 결과 검색:

색인 벤치마크 결과:

추가 보너스: 비용 절감

낮은 지연 시간으로 뛰어난 성능을 제공하는 데 중점을 두고 있지만, 새로운 하드웨어의 효율성은 Elasticsearch 프로젝트의 비용에도 직접적이고 긍정적인 영향을 미칩니다.

Elasticsearch Serverless 요금제는 사용량 기반이므로, 사용한 인제스트 및 검색 리소스에 대해서만 비용을 지불하면 됩니다. 더 빠른 신규 하드웨어는 효율성이 높기 때문에 대부분의 프로젝트에서 종종 더 적은 리소스를 사용하여 워크로드가 작업을 완료하게 되어 본질적인 비용 절감으로 이어집니다. 높은 금액을 지불하지 않고도 프리미엄 수준의 성능 향상을 얻을 수 있습니다. 최적화된 효율성이라고 할 수 있죠.

이것이 개발자에게 의미하는 바는 무엇일까요?

Elastic에서 이 인프라 업그레이드를 전적으로 관리하므로 손가락 하나 까딱하지 않아도 됩니다. 마이그레이션이나 구성 변경도 필요 없습니다. 이러한 개선 사항은 모든 AWS 기반 서버리스 프로젝트에 즉각적으로 자동 적용됩니다.

업그레이드의 효과:

• 더 빠른 애플리케이션 구축: 기본 검색 플랫폼이 사용자가 요구하는 속도를 제공한다는 것을 알기 때문에 기능 개발 속도에 집중할 수 있습니다.
• 자신감 있는 혁신: 플랫폼이 최고의 성능으로 부하를 처리할 수 있다는 확신을 가지고 벡터 검색 및 관련성 순위와 같은 복잡한 AI 기능을 포함한 새로운 검색, 통합 가시성 및 보안 기능을 배포하세요.
• 스택 간소화: 인프라 관리, 용량 계획 및 확장을 처리하는 완전 관리형 서비스를 사용하여 코드와 데이터에 집중할 수 있습니다.
  

요건

• NodeJS 버전 18 이상
• OpenAI API 키
• Elasticsearch 8.x+ 배포

LangGraph를 생산 HITL 시스템에 사용하는 이유

이전 문서에서는 LLM과 조건부 엣지를 사용하여 자동으로 의사결정을 내리고 결과를 표시하는 RAG 시스템을 구축하는 데 있어 LangGraph와 그 이점에 대해 소개했습니다. 때로는 시스템이 처음부터 끝까지 자율적으로 작동하는 것이 아니라 사용자가 실행 루프 내에서 옵션을 선택하고 의사 결정을 내리기를 원할 때가 있습니다. 이 개념은 휴먼 인 더 루프라고 합니다.

휴먼 인 더 루프 또는 인 더 루프

이는 실제 사람이 AI 시스템과 상호 작용하여 더 많은 컨텍스트를 제공하고, 응답을 평가하고, 응답을 편집하고, 추가 정보를 요청하는 등의 작업을 수행할 수 있는 AI 개념입니다. 이는 규정 준수, 의사 결정 또는 콘텐츠 생성 등 오류 허용 오차가 낮은 시나리오에서 매우 유용하며, LLM 출력의 신뢰성을 개선하는 데 도움이 됩니다.

일반적인 예는 코딩 어시스턴트가 터미널에서 특정 명령을 실행할 권한을 요청하거나 코딩을 시작하기 전에 승인할 단계별 사고 과정을 보여 주는 경우입니다.

Elasticsearch와 LangGraph의 상호 작용 방식

LangChain은 전체 텍스트 또는 시맨틱 검색을 실행하는 데 유용한 전체 텍스트 또는 시맨틱 검색을 실행하는 데 유용한 LangGraph 애플리케이션 내에서 Elasticsearch를 벡터 저장소로 사용하고 쿼리를 수행할 수 있게 해주며, LangGraph는 특정 워크플로우, 도구 및 상호 작용을 정의하는 데 사용됩니다. 또한 HITL을 사용자와의 추가적인 상호 작용 계층으로 추가합니다.

실용적인 구현: 휴먼 인 더 루프

변호사가 최근에 수임한 사건에 대해 궁금한 점이 있는 경우를 가정해 보겠습니다. 적절한 도구가 없다면 그는 법률 조항과 판례를 일일이 검색하고, 전문을 읽은 다음, 그것들이 자신의 상황에 어떻게 적용되는지 해석해야 할 것입니다. 그러나 LangGraph와 Elasticsearch를 사용하면 법률 판례 데이터베이스를 검색하고 변호사가 제공한 구체적인 세부 사항과 맥락을 통합한 판례 분석을 생성하는 시스템을 구축할 수 있습니다.

변호사가 법률 질문을 제출하는 순간부터 워크플로우가 시작됩니다. 시스템은 Elasticsearch에서 벡터 검색을 수행하여 가장 관련성이 높은 판례를 검색한 후 자연어를 사용해 변호사가 선택할 수 있도록 제시합니다. 선택 후 LLM은 분석 초안을 생성하고 정보가 완전한지 확인합니다. 이 시점에서 워크플로우는 두 가지 경로 중 하나를 따를 수 있습니다. 모든 것이 명확하다면 최종 분석을 생성하기 위해 직접 진행하고, 그렇지 않다면 변호사에게 명확화를 요청하기 위해 일시 중지합니다. 누락된 컨텍스트가 제공되면 시스템은 설명을 고려하여 분석을 완료하고 반환합니다.

다음은 LangGraph에서 생성한 그래프로, 개발이 완료되었을 때 앱의 최종 모습을 보여줍니다. 각 노드는 도구 또는 기능을 나타냅니다.

데이터 세트

이 예제에 사용되는 데이터 세트는 다음과 같습니다. 이 데이터 세트는 서비스 지연과 관련된 사례, 법원의 판결 이유 및 최종 결과를 설명하는 법적 판례 모음입니다.

[
  {
    "pageContent": "Legal precedent: Case B - Service delay not considered breach. A consulting contract used term 'timely delivery' without specific dates. A three-week delay occurred but contract lacked explicit schedule. Court ruled no breach as parties had not defined concrete timeline and delay did not cause demonstrable harm.",
    "metadata": {
      "caseId": "CASE-B-2022",
      "contractType": "consulting agreement",
      "delayPeriod": "three weeks",
      "outcome": "no breach found",
      "reasoning": "no explicit deadline defined, no demonstrable harm",
      "keyTerms": "timely delivery, open terms, schedule definition",
      "title": "Case B: Delay Without Explicit Schedule"
    }
  },
  ...
]

데이터 수집 및 인덱스 설정

인덱스 설정 및 데이터 수집 로직은 dataIngestion.ts 파일에 정의되어 있으며, 여기서 인덱스 생성을 처리하는 함수를 선언합니다. 이 설정은 Elasticsearch용 LangChain 벡터 저장소 인터페이스와 호환됩니다.

참고: 매핑 설정은 dataIngestion.ts 파일에도 포함되어 있습니다.

패키지 설치 및 환경 변수 설정

기본 설정으로 Node.js 프로젝트를 초기화합니다.

• @elastic/elasticsearch: Node.js용 Elasticsearch 클라이언트입니다. 연결, 인덱스 생성 및 쿼리 실행에 사용됩니다.
• @langchain/community: ElasticVectorSearch 스토어를 비롯한 커뮤니티 지원 도구에 대한 통합을 제공합니다.
• @langchain/core: 체인, 프롬프트, 유틸리티와 같은 LangChain의 핵심 구성 요소입니다.
• @langchain/langgraph: 그래프 기반 오케스트레이션을 추가하여 노드, 엣지 및 상태 관리를 포함하는 워크플로우를 지원합니다.
• @langchain/openai: LangChain을 통해 OpenAI 모델(LLM 및 임베딩)에 대한 액세스를 제공합니다.
• dotenv:.env 파일에서 process.env로 환경 변수를 로드합니다.
• tsx: TypeScript 코드를 실행하는 데 유용한 도구입니다.

콘솔에서 다음 명령어를 실행하여 모든 항목을 설치하세요.

npm install @elastic/elasticsearch @langchain/community @langchain/core @langchain/langgraph @langchain/openai dotenv --legacy-peer-deps && npm install --save-dev tsx

.env 파일을 생성하여 환경 변수를 설정합니다.

ELASTICSEARCH_ENDPOINT=
ELASTICSEARCH_API_KEY=
OPENAI_API_KEY=

타입 안전성과 더 나은 개발자 경험을 제공하기 때문에 TypeScript를 사용하여 코드를 작성할 것입니다. main.ts라는 이름의 TypeScript 파일을 만들고 다음 섹션의 코드를 삽입합니다.

패키지 가져오기

main.ts 파일에서 필요한 모듈을 가져오고 환경 변수 구성을 초기화하는 것으로 시작합니다. 여기에는 핵심 LangGraph 구성 요소, OpenAI 모델 통합, Elasticsearch 클라이언트가 포함됩니다.

또한 DataingEstion.ts 파일에서 다음을 가져옵니다.

• ingestData: 인덱스를 생성하고 데이터를 수집하는 함수입니다.
• Document 및 DocumentMetadata: 데이터셋 문서 구조를 정의하는 인터페이스입니다.

Elasticsearch 벡터 저장소 클라이언트, 임베딩 클라이언트 및 OpenAI 클라이언트

이 코드는 벡터 저장소, 임베딩 클라이언트 및 OpenAI 클라이언트 하나를 초기화합니다.

const VECTOR_INDEX = "legal-precedents";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });
const embeddings = new OpenAIEmbeddings({
  model: "text-embedding-3-small",
});

const esClient = new Client({
  node: process.env.ELASTICSEARCH_ENDPOINT,
  auth: {
    apiKey: process.env.ELASTICSEARCH_API_KEY ?? "",
  },
});

const vectorStore = new ElasticVectorSearch(embeddings, {
  client: esClient,
  indexName: VECTOR_INDEX,
});

애플리케이션 워크플로우 상태 스키마는 노드 간 통신에 도움이 됩니다.

const LegalResearchState = Annotation.Root({
  query: Annotation(),
  analyzedConcepts: Annotation(),
  precedents: Annotation(),
  selectedPrecedent: Annotation(),
  draftAnalysis: Annotation(),
  ambiguityDetected: Annotation(),
  userClarification: Annotation(),
  finalAnalysis: Annotation(),
});

상태 객체에서는 사용자의 쿼리, 쿼리에서 추출된 개념, 검색된 법적 판례 및 감지된 모호성을 노드를 통해 전달합니다. 또한 사용자가 선택한 판례, 그 과정에서 생성된 분석 초안, 모든 설명이 완료된 후 최종 분석도 추적합니다.

노드

searchPrecedents: 이 노드는 사용자의 입력에 따라 Elasticsearch 벡터 저장소에서 유사성 검색을 수행합니다. 이 기능은 일치하는 문서를 최대 5개까지 검색하여 사용자가 검토할 수 있도록 인쇄합니다.

async function searchPrecedents(state: typeof LegalResearchState.State) {
  console.log(
    "📚 Searching for relevant legal precedents with query:\n",
    state.query
  );

  const results = await vectorStore.similaritySearch(state.query, 5);
  const precedents = results.map((d) => d as Document);

  console.log(`Found ${precedents.length} relevant precedents:\n`);

  for (let i = 0; i < precedents.length; i++) {
    const p = precedents[i];
    const m = p.metadata;
    console.log(
      `${i + 1}. ${m.title} (${m.caseId})\n` +
        `   Type: ${m.contractType}\n` +
        `   Outcome: ${m.outcome}\n` +
        `   Key reasoning: ${m.reasoning}\n` +
        `   Delay period: ${m.delayPeriod}\n`
    );
  }

  return { precedents };
}

precedentSelection: 이 노드를 사용하면 사용자가 자연어를 사용하여 근접 검색에서 검색된 사용 사례 중 질문과 가장 잘 일치하는 사용 사례를 선택할 수 있습니다. 이 시점에서 애플리케이션은 워크플로우를 중단하고 사용자 입력을 기다립니다.

function precedentSelection(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #1: Human input needed\n");
  const question = "👨‍⚖️  Which precedent is most similar to your case? ";
  const userChoice = interrupt({ question });

  return { userChoice };
}

selectPrecedent: 이 노드는 검색된 문서 중 하나를 선택할 수 있도록 해석할 사용자 입력을 검색된 문서와 함께 전송합니다. LLM은 사용자의 자연어 입력으로부터 추론한 문서를 나타내는 숫자를 반환함으로써 이 작업을 수행합니다.

async function selectPrecedent(state: typeof LegalResearchState.State) {
  const precedents = state.precedents || [];
  const userInput = (state as any).userChoice || "";

  const precedentsList = precedents
    .map((p, i) => {
      const m = p.metadata;
      return `${i + 1}. ${m.caseId}: ${m.title} - ${m.outcome}`;
    })
    .join("\n");

  const structuredLlm = llm.withStructuredOutput({
    name: "precedent_selection",
    schema: {
      type: "object",
      properties: {
        selected_number: {
          type: "number",
          description:
            "The precedent number selected by the lawyer (1-based index)",
          minimum: 1,
          maximum: precedents.length,
        },
      },
      required: ["selected_number"],
    },
  });

  const prompt = `
    The lawyer said: "${userInput}"

    Available precedents:
    ${precedentsList}

    Which precedent number (1-${precedents.length}) matches their selection?
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are an assistant that interprets lawyer's selection and returns the corresponding precedent number.",
    },
    { role: "user", content: prompt },
  ]);

  const selectedIndex = response.selected_number - 1;
  const selectedPrecedent = precedents[selectedIndex] || precedents[0];

  console.log(`✅ Selected: ${selectedPrecedent.metadata.title}\n`);
  return { selectedPrecedent };
}

createDraft: 이 노드는 사용자가 선택한 판례를 기반으로 초기 법적 분석을 생성합니다. LLM을 사용하여 선택된 판례가 변호사의 질문에 어떻게 적용되는지 평가하고, 시스템이 진행하기에 충분한 정보를 가지고 있는지 결정합니다.

판례를 바로 적용할 수 있는 경우, 노드는 초안 분석 결과를 생성하고 올바른 경로를 따라 최종 노드로 이동합니다. LLM이 모호성, 예를 들어 정의되지 않은 계약 조건, 누락된 타임라인 세부 사항 또는 불명확한 조건을 감지하면 명확화가 필요함을 나타내는 플래그와 함께 제공되어야 하는 구체적인 정보 목록을 반환합니다. 이 경우 모호성으로 인해 그래프의 왼쪽 경로가 선택됩니다.

async function createDraft(state: typeof LegalResearchState.State) {
  console.log("📝 Drafting initial legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { draftAnalysis: "" };

  const m = precedent.metadata;

  const structuredLlm = llm.withStructuredOutput({
    name: "draft_analysis",
    schema: {
      type: "object",
      properties: {
        needs_clarification: {
          type: "boolean",
          description:
            "Whether the analysis requires clarification about contract terms or context",
        },
        analysis_text: {
          type: "string",
          description: "The draft legal analysis or the ambiguity explanation",
        },
        missing_information: {
          type: "array",
          items: { type: "string" },
          description:
            "List of specific information needed if clarification is required (empty if no clarification needed)",
        },
      },
      required: ["needs_clarification", "analysis_text", "missing_information"],
    },
  });

  const prompt = `
    Based on this precedent:
    Case: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    Key terms: ${m.keyTerms}

    And the lawyer's question: "${state.query}"

    Draft a legal analysis applying this precedent to the question.
    
    If you need more context about the specific contract terms, timeline details, 
    or other critical information to provide accurate analysis, set needs_clarification 
    to true and list what information is missing.
    
    Otherwise, provide the legal analysis directly.
  `;

  const response = await structuredLlm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant that analyzes cases and identifies when additional context is needed.",
    },
    { role: "user", content: prompt },
  ]);

  let displayText: string;
  if (response.needs_clarification) {
    const missingInfoList = response.missing_information
      .map((info: string, i: number) => `${i + 1}. ${info}`)
      .join("\n");
    displayText = `AMBIGUITY DETECTED:\n${response.analysis_text}\n\nMissing information:\n${missingInfoList}`;
  } else {
    displayText = `ANALYSIS:\n${response.analysis_text}`;
  }

  console.log(displayText + "\n");

  return {
    draftAnalysis: displayText,
    ambiguityDetected: response.needs_clarification,
  };
}

그래프가 취할 수 있는 두 가지 경로는 다음과 같습니다.

왼쪽 경로에는 설명을 처리하는 추가 노드가 포함되어 있습니다.

requestClarification: 이 노드는 초안 분석에 필수 컨텍스트가 부족하다고 시스템이 식별하면 두 번째 휴먼 인 더 루프 단계를 트리거합니다. 워크플로우가 중단되고 사용자에게 이전 노드에서 감지한 누락된 계약 세부 정보를 명확히 해달라는 메시지가 표시됩니다.

function requestClarification(state: typeof LegalResearchState.State) {
  console.log("\n⚖️  HITL #2: Additional context needed\n");
  const userClarification = interrupt({
    question: "👨‍⚖️  Please provide clarification about your contract terms:",
  });
  return { userClarification };
}

generateFinalAnalysis: 이 노드는 선택한 판례와 필요한 경우 사용자가 제공한 추가 컨텍스트를 결합하여 최종 법률 분석을 생성합니다. 이전 HITL 단계에서 수집한 설명을 사용하여, LLM은 판례의 추론, 사용자가 제공한 계약 세부 정보 및 위반이 발생했는지 여부를 결정하는 조건을 종합합니다.

이 노드는 법적 해석과 실용적인 권장 사항을 통합한 완전한 분석을 출력합니다.

async function generateFinalAnalysis(state: typeof LegalResearchState.State) {
  console.log("📋 Generating final legal analysis...\n");

  const precedent = state.selectedPrecedent;
  if (!precedent) return { finalAnalysis: "" };

  const m = precedent.metadata;

  const prompt = `
    Original question: "${state.query}"
    
    Selected precedent: ${m.title}
    Outcome: ${m.outcome}
    Reasoning: ${m.reasoning}
    
    Lawyer's clarification: "${state.userClarification}"
    
    Provide a comprehensive legal analysis integrating:
    1. The selected precedent's reasoning
    2. The lawyer's specific contract context
    3. Conditions for breach vs. no breach
    4. Practical recommendations
  `;

  const response = await llm.invoke([
    {
      role: "system",
      content:
        "You are a legal research assistant providing comprehensive analysis.",
    },
    { role: "user", content: prompt },
  ]);

  const finalAnalysis = response.content as string;

  console.log(
    "\n" +
      "=".repeat(80) +
      "\n" +
      "⚖️  FINAL LEGAL ANALYSIS\n" +
      "=".repeat(80) +
      "\n\n" +
      finalAnalysis +
      "\n\n" +
      "=".repeat(80) +
      "\n"
  );

  return { finalAnalysis };
}

그래프 작성:

const workflow = new StateGraph(LegalResearchState)
  .addNode("analyzeQuery", analyzeQuery)
  .addNode("searchPrecedents", searchPrecedents)
  .addNode("precedentSelection", precedentSelection)
  .addNode("selectPrecedent", selectPrecedent)
  .addNode("createDraft", createDraft)
  .addNode("requestClarification", requestClarification)
  .addNode("generateFinalAnalysis", generateFinalAnalysis)
  .addEdge("__start__", "analyzeQuery")
  .addEdge("analyzeQuery", "searchPrecedents")
  .addEdge("searchPrecedents", "precedentSelection") // HITL #1
  .addEdge("precedentSelection", "selectPrecedent")
  .addEdge("selectPrecedent", "createDraft")
  .addConditionalEdges(
    "createDraft",
    (state: typeof LegalResearchState.State) => {
      // If ambiguity detected, request clarification (HITL #2)
      if (state.ambiguityDetected) return "needsClarification";
      // Otherwise, generate final analysis
      return "final";
    },
    {
      needsClarification: "requestClarification",
      final: "generateFinalAnalysis",
    }
  )
  .addEdge("requestClarification", "generateFinalAnalysis") // HITL #2
  .addEdge("generateFinalAnalysis", "__end__");

그래프에서 조건부 엣지가 "최종" 경로를 선택하는 조건을 정의한다는 것을 볼 수 있습니다. 위에서 살펴본 바와 같이, 이제 결정은 초안 분석에서 추가 설명이 필요한 모호성을 발견했는지 여부에 따라 달라집니다.

모두 합쳐서 실행:

await ingestData();

// Compile workflow
const app = workflow.compile({ checkpointer: new MemorySaver() });
const config = { configurable: { thread_id: "hitl-circular-thread" } };

await saveGraphImage(app);

// Execute workflow
const legalQuestion =
    "Does a pattern of repeated delays constitute breach even if each individual delay is minor?"; 

console.log(`⚖️  LEGAL QUESTION: "${legalQuestion}"\n`);

let currentState = await app.invoke({ query: legalQuestion }, config);

// Handle all interruptions in a loop
while ((currentState as any).__interrupt__?.length > 0) {
  console.log("\n💭 APPLICATION PAUSED WAITING FOR USER INPUT...");

  const interruptQuestion = (currentState as any).__interrupt__[0]?.value
    ?.question;
  const userChoice = await getUserInput(
    interruptQuestion || "👤 YOUR CHOICE: "
  );

  currentState = await app.invoke(
    new Command({ resume: userChoice }),
    config
  );
}

스크립트 실행:

모든 코드가 할당되었으므로 터미널에 다음 명령어를 입력하여 main.ts 파일을 실행합니다.

tsx main.ts

스크립트가 실행되면, "반복되는 지연 패턴이 각 개별 지연이 경미하더라도 침해에 해당하는가?"라는 질문이 Elasticsearch로 전송되어 근접 검색을 수행하게 되며, 인덱스에서 얻은 결과가 표시됩니다. 앱은 쿼리와 일치하는 여러 관련 판례를 감지하여 실행을 일시정지하고 사용자에게 어떤 법적 판례가 가장 적합한지 명확히 설명하도록 요청합니다.

📚 Searching for relevant legal precedents with query:
 Does a pattern of repeated delays constitute breach even if each individual delay is minor?
Found 5 relevant precedents:

1. Case H: Pattern of Repeated Delays (CASE-H-2021)
   Type: ongoing service agreement
   Outcome: breach found
   Key reasoning: pattern demonstrated failure to perform, cumulative effect
   Delay period: multiple instances

2. Case E: Minor Delay Quality Maintained (CASE-E-2022)
   Type: service agreement
   Outcome: minor breach only
   Key reasoning: delay minimal, quality maintained, termination unjustified
   Delay period: five days

3. Case A: Delay Breach with Operational Impact (CASE-A-2023)
   Type: service agreement
   Outcome: breach found
   Key reasoning: delay affected operations and caused financial harm
   Delay period: two weeks

4. Case B: Delay Without Explicit Schedule (CASE-B-2022)
   Type: consulting agreement
   Outcome: no breach found
   Key reasoning: no explicit deadline defined, no demonstrable harm
   Delay period: three weeks

5. Case C: Justified Delay External Factors (CASE-C-2023)
   Type: construction service
   Outcome: no breach found
   Key reasoning: external factors beyond control, force majeure applied
   Delay period: one month

⚖️  HITL #1: Human input needed

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? 

이 애플리케이션의 흥미로운 점은 자연어를 사용하여 하나의 옵션을 선택할 수 있고, LLM이 사용자의 입력을 해석하여 올바른 선택을 결정할 수 있다는 점입니다. "Case H" 텍스트를 입력하면 어떻게 되는지 살펴봅시다.

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Which precedent is most similar to your case? Case H

✅ Selected: Case H: Pattern of Repeated Delays

📝 Drafting initial legal analysis...

AMBIGUITY DETECTED:
Based on Case H, a pattern of repeated delays can indeed constitute a breach of contract, even if each individual delay is minor. The outcome in Case H indicates that the cumulative effect of these minor delays led to a significant failure to perform the contractual obligations adequately. The reasoning emphasizes that consistent performance is critical in fulfilling the terms of a contract. Therefore, if the repeated delays create a situation where the overall performance is hindered, this pattern could be interpreted as a breach. However, the interpretation may depend on the specific terms of the contract at issue, as well as the expectations of performance set forth in that contract.

Missing information:
1. Specific contract terms regarding performance timelines
2. Details on the individual delays (duration, frequency)
3. Context on consequences of delays stated in the contract
4. Other parties' expectations or agreements related to performance


⚖️  HITL #2: Additional context needed


💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms:

이 모델은 사용자의 설명을 받아 워크플로우에 통합하여 충분한 컨텍스트가 제공되면 최종 분석을 진행합니다. 이 단계에서는 이전에 감지된 모호성을 활용하여 초안 분석에서 법적 해석에 의미 있는 영향을 미칠 수 있는 누락된 계약 세부 사항을 강조 표시합니다. 이러한 '누락된 정보' 항목은 신뢰할 수 있는 최종 의견을 도출하기 전에 불확실성을 해소하기 위해 어떤 설명이 필요한지 판단하는 데 도움이 됩니다.

사용자는 다음 입력에 설명을 요청한 내용을 포함해야 합니다. "계약서에는 기간 없이 ‘신속한 배송’이 요구됩니다. 6개월 동안 2-4일의 지연이 8번 발생했습니다. 3번의 고객 마감일을 놓쳐 50,000달러의 손실이 발생했습니다. 공급업체에 통보했지만 패턴은 계속되었습니다."로 시도해 보겠습니다.

💭 APPLICATION PAUSED WAITING FOR USER INPUT...
👨‍⚖️  Please provide clarification about your contract terms: Contract requires "prompt delivery" without timelines. 8 delays of 2-4 days over 6 months. $50K in losses from 3 missed client deadlines. Vendor notified but pattern continued.

📋 Generating final legal analysis...

================================================================================
⚖️  FINAL LEGAL ANALYSIS
================================================================================

To analyze the question of whether a pattern of repeated minor delays constitutes a breach of contract, we need to combine insights from the selected precedent, the specifics of the lawyer's contract situation, conditions that typically govern breach versus non-breach, and practical recommendations for the lawyer moving forward.

### 1. Selected Precedent's Reasoning

The precedent case, referred to as Case H, found that a pattern of repeated delays amounted to a breach of contract. The court reasoned that even minor individual delays, when considered cumulatively, demonstrated a failure to perform as stipulated in the contract. The underlying rationale was that the cumulative effect of these minor delays could significantly undermine the purpose of the contract, which typically aims for timely performance and reliable delivery.

### 2. Lawyer's Specific Contract Context

In the lawyer's situation, the contract specified "prompt delivery" but did not provide a strict timeline. The vendor experienced 8 delays ranging from 2 to 4 days over a period of 6 months. These delays culminated in $50,000 in losses due to three missed client deadlines. The vendor was notified regarding these delays; however, the pattern of delays persisted.

Key considerations include:
- **Nature of the Obligations**: While “prompt delivery” does not define a strict timeline, it does imply an expectation for timely performance.
- **Material Impact**: The missed client deadlines indicate that these delays had a material adverse effect on the lawyer's ability to fulfill contractual obligations to third parties, likely triggering damages.

### 3. Conditions for Breach vs. No Breach

**Conditions for Breach**:
- **Pattern and Cumulative Effect**: Similar to the reasoning in Case H, evidence of a habitual pattern of delays can amount to a breach. Even if individual delays are minor, when combined, they may show a lack of diligence or reliability by the vendor.
- **Materiality**: The impact of these delays is crucial. If the cumulative delays adversely affect the contract's purpose or cause significant losses, this reinforces the case for a breach.
- **Notification and Opportunity to Cure**: The fact that the vendor was notified of the delays and failed to rectify the behavior can often be interpreted as a further indication of breach.

**Conditions for No Breach**:
- **Non-Material Delays**: If the delays did not affect the overall contractual performance or client obligations, this may lessen the likelihood of establishing a breach. However, given the risks and losses involved, this seems less relevant in this scenario.
- **Force Majeure or Justifiable Delays**: If the vendor could show that these delays were due to justify circumstances not within their control, it may potentially provide a defense against breach claims.

### 4. Practical Recommendations

1. **Assess Damages**: Document the exact nature of the financial losses incurred due to the missed deadlines to substantiate claims of damages.
  
2. **Gather Evidence**: Collect all communication regarding the delays, including any notifications sent to the vendor about the issues.

3. **Consider Breach of Contract Action**: Based on the precedent and accumulated delays, consider formalized communication to the vendor regarding a breach of contract claim, highlighting both the pattern and the impact of these repeated delays.

4. **Evaluate Remedies**: Depending upon the contract specifics, the lawyer may wish to pursue several remedies, including:
   - **Compensatory Damages**: For the financial losses due to missed deadlines.
   - **Specific Performance**: If timely delivery is critical and can still be enforced.
   - **Contract Termination**: Depending on the severity, terminating the contract and seeking replacements may be warranted.

5. **Negotiate Terms**: If continuing to work with the current vendor is strategic, the lawyer should consider renegotiating terms for performance guarantees or penalties for further delays.

6. **Future Contracts**: In future contracts, consider including explicit timelines and conditions for prompt delivery, as well as specified damages for delays to better safeguard against this issue.

By integrating the legal principles from the precedent with the specific context and conditions outlined, the lawyer can formulate a solid plan to address the repeated delays by the vendor effectively.

이 출력은 워크플로우의 마지막 단계로, 모델이 선택한 판례(사례 H)와 변호사의 설명을 통합하여 완전한 법률 분석을 생성하는 과정을 보여줍니다. 이 시스템은 지연 패턴이 위반에 해당하는 이유를 설명하고, 이러한 해석을 뒷받침하는 요인을 간략하게 설명하며, 실질적인 권장 사항을 제공합니다. 전반적으로, 이 출력은 HITL 명확화가 어떻게 모호성을 해소하고 모델이 타당한 맥락에 맞는 법적 의견을 도출할 수 있도록 하는지를 보여줍니다.

기타 실제 시나리오

Elasticsearch, LangGraph, 휴먼 인 더 루프 등을 사용하는 이러한 종류의 애플리케이션은 다른 종류의 앱에서도 유용하게 사용될 수 있습니다.

• 도구 호출을 실행하기 전에 검토합니다. 예를 들어, 금융 거래에서는 주문이 입력되기 전에 인간이 매수/매도 주문을 승인합니다.
• 필요에 따라 추가 매개변수를 제공합니다. 예를 들어, 고객 지원 분류 과정에서 AI가 고객 문제에 대해 여러 가지 가능한 해석을 제시할 때 상담원이 올바른 문제 범주를 선택하는 경우에 유용합니다.

그리고 휴먼 인 더 루프가 판도를 바꾸는 요소가 될 많은 사용 사례들이 발견되어야 합니다.

결론

LangGraph와 Elasticsearch를 사용하면 자체적으로 결정을 내리고 선형 워크플로우로 작동하거나 한 경로 또는 다른 경로를 선택하는 조건을 가진 에이전트를 구축할 수 있습니다. 휴먼 인 더 루프를 통해 에이전트는 실제 사용자를 의사 결정 과정에 참여시켜 문맥상의 공백을 메우고 내결함성이 중요한 시스템에 대한 확인을 요청할 수 있습니다.

이 접근 방식의 장점 중 하나는 Elasticsearch 기능을 사용하여 대규모 데이터 세트를 필터링한 다음 LLM을 사용하여 사용자가 선택한 단일 문서를 가져올 수 있다는 것입니다. Elasticsearch만 사용하면 이 마지막 단계는 훨씬 더 까다로울 것입니다. 왜냐하면 인간이 자연어를 사용하여 결과를 언급할 수 있는 방법이 많기 때문입니다.

이 접근 방식은 전체 데이터 세트가 아닌 최종 결정을 내리는 데 필요한 정보만 LLM에 전송하므로 시스템의 속도와 토큰 효율을 유지합니다. 동시에 사용자의 의도를 매우 정확하게 감지하고 원하는 옵션이 선택될 때까지 반복합니다.

목표는 로그 구문 분석(필드 추출)과 로그 분할(소스 식별)을 모두 처리할 수 있는 자동화되고 적응형 접근 방식으로 전환하는 것이었습니다. 대규모 언어 모델(LLM)이 코드 구문과 의미론적 패턴에 대한 내재된 이해를 통해 이러한 작업을 최소한의 인간 개입으로 자동화할 수 있다고 가정했습니다.

Streams에서 이미 이 기능을 사용 가능하다는 기쁜 소식을 전해 드립니다!

데이터 세트 설명

PoC 목적으로 Loghub 로그 컬렉션을 선택했습니다. 조사를 위해 다음 주요 분야에서 대표적인 샘플을 선정했습니다.

• 분산 시스템: HDFS(Hadoop 분산 파일 시스템)와 Spark 데이터 세트를 사용했습니다. 여기에는 빅데이터 플랫폼에서 흔히 볼 수 있는 정보, 디버그, 오류 메시지가 섞여 있습니다.
• 서버 및 웹 애플리케이션: Apache 웹 서버 및 OpenSSH의 로그는 액세스, 오류 및 보안 관련 이벤트의 귀중한 소스를 제공했습니다. 이는 웹 트래픽을 모니터링하고 잠재적 위협을 탐지하는 데 매우 중요합니다.
• 운영 체제: Linux 및 Windows의 로그를 포함했습니다. 이러한 데이터 세트는 운영팀이 매일 접하는 일반적인 반정형 시스템 수준 이벤트를 나타냅니다.
• 모바일 시스템: 모바일 환경에서 발생하는 로그를 모델이 처리할 수 있는지 확인하기 위해 안드로이드 데이터 세트를 포함했습니다. 이러한 로그는 종종 상세한 내용을 담고 있으며 모바일 디바에스에서 발생하는 다양한 애플리케이션 및 시스템 수준의 활동을 기록합니다.
• 슈퍼컴퓨터: 고성능 컴퓨팅(HPC) 환경에서 성능을 테스트하기 위해 고도로 구조화된 로그와 특정 도메인 용어를 특징으로 하는 BGL (Blue Gene/L) 데이터 세트를 통합했습니다.

Loghub 컬렉션의 주요 장점은 로그가 대부분 정제되지 않고 레이블이 지정되지 않아 노이즈가 많은 실시간 프로덕션 환경을 마이크로서비스 아키텍처로 미러링한다는 점입니다.

로그 예:

[Sun Dec 04 20:34:21 2005] [notice] jk2_init() Found child 2008 in scoreboard slot 6
[Sun Dec 04 20:34:25 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
[Mon Dec 05 11:06:51 2005] [notice] workerEnv.init() ok /etc/httpd/conf/workers2.properties
17/06/09 20:10:58 INFO output.FileOutputCommitter: Saved output of task 'attempt_201706092018_0024_m_000083_1138' to hdfs://10.10.34.11:9000/pjhe/test/1/_temporary/0/task_201706092018_0024_m_000083
17/06/09 20:10:58 INFO mapred.SparkHadoopMapRedUtil: attempt_201706092018_0024_m_000083_1138: Committed

또한 가장 일반적인 도메인에서 추가 로그를 수집하기 위해 일반적인 웹 애플리케이션과 데이터베이스 설정으로 Kubernetes 클러스터를 생성했습니다.

일반적인 로그 필드의 예: 타임스탬프, 로그 레벨(정보, 경고, 오류), 소스, 메시지.

LLM을 이용한 퓨샷 로그 구문 분석

첫 번째 실험은 근본적인 질문에 초점을 맞췄습니다: LLM이 핵심 필드를 안정적으로 식별하고 이를 추출하기 위한 일관된 구문 분석 규칙을 생성할 수 있는가?

모델에 원시 로그 샘플을 분석하고 정규식(Regex) 및 Grok 형식의 로그 구문 분석 규칙을 생성하도록 요청했습니다. 그 결과, 이 접근 방식은 잠재력이 많지만 구현에 상당한 어려움이 있음을 파악했습니다.

높은 신뢰도 및 상황 인식

초기 결과는 고무적이었습니다. LLM은 제공된 퓨샷 예시와 일치하는 구문 분석 규칙을 높은 신뢰도로 생성하는 뛰어난 능력을 보여주었습니다. 이 모델은 단순한 패턴 매칭 외에도 로그 소스를 정확하게 식별하고 이름을 지정할 수 있는 로그 이해 능력도 보여주었습니다(예: 상태 추적 앱, Nginx 웹 앱, Mongo 데이터베이스).

입력 샘플의 '골디락스' 딜레마

실험 결과, 입력 샘플에 대한 극도의 민감성 때문에 모델의 견고성이 상당히 부족하다는 점이 금방 드러났습니다. 모델의 성능은 프롬프트에 포함된 특정 로그 예시에 따라 크게 변동했습니다. 로그 샘플에는 충분히 다양한 로그가 포함되어야 하는 로그 유사성 문제가 있음을 확인했습니다.

• 너무 동질적인 경우(과적합): 입력 로그가 너무 유사하면 LLM은 과도하게 세부화하는 경향이 있습니다. 스택 추적의 특정 Java 클래스 이름과 같은 가변 데이터를 템플릿의 정적 부분으로 처리합니다. 이로 인해 극히 일부 로그만 다루고 사용할 수 없는 필드를 추출하는 취약한 규칙이 생성됩니다.
• 너무 이질적인 경우(혼란): 반대로 샘플에 형식상의 편차가 심하거나, 더 심각하게는 진행률 표시줄, 메모리 테이블 또는 ASCII 아트와 같은 '엉터리 로그'가 포함되면 모델은 공통분모를 찾는 데 어려움을 겪습니다. 이 경우 복잡하고 불완전한 정규식을 생성하거나 전체 줄을 단일 메시지 블롭 필드로 과도하게 일반화하는 경우가 많습니다.

컨텍스트 윈도우 제약 조건

또한 컨텍스트 윈도우 병목 현상에 직면했습니다. 입력 로그가 길거나, 이질적이거나, 추출 가능한 필드가 많을 경우, 모델의 출력 결과가 종종 저하되어 "정리되지 않은" 상태가 되거나 출력 컨텍스트 윈도우에 맞지 않을 정도로 길어졌습니다. 당연히 청킹이 이러한 문제를 해결하는 데 도움이 됩니다. 문자 기반 및 엔티티 기반 구분자를 사용하여 로그를 분할함으로써, 모델이 노이즈에 압도되지 않고 주요 필드를 추출하는 데 집중할 수 있도록 도울 수 있었습니다.

일관성 및 표준화 격차

모델이 규칙을 성공적으로 생성한 경우에도 다음과 같이 약간의 불일치가 발견되었습니다.

• 서비스 이름 지정 변형: 모델은 동일한 엔티티에 대해 서로 다른 이름을 제안합니다(예: 실행마다 소스를 'Spark', 'Apache Spark' 및 'Spark Log Analytics'로 레이블 지정).
• 필드 이름 지정의 변형: 필드 이름이 표준화되지 않았습니다(예: id , service.id , device.id). 표준화된 Elastic 필드 이름 지정을 사용하여 이름을 정규화했습니다.
• 해상도 편차: 필드 추출의 해상도는 입력 로그가 서로 얼마나 유사한지에 따라 달라집니다.

로그 형식 지문

로그 유사성 문제를 해결하기 위해 고성능 휴리스틱인 로그 형식 지문(LFF)을 도입합니다.

원시적이고 노이즈가 많은 로그를 LLM에 직접 입력하는 대신, 먼저 결정론적 변환을 적용하여 각 메시지의 기본 구조를 드러냅니다. 이 전처리 단계는 가변 데이터를 추상화하여 관련 로그를 그룹화할 수 있는 단순화된 '지문'을 생성합니다.

매핑 로직은 속도와 일관성을 보장하기 위해 다음과 같이 간단합니다.

1. 숫자 추상화: 모든 숫자 시퀀스(0-9)는 단일 '0'으로 대체됩니다.
2. 텍스트 추상화: 공백이 있는 알파벳 문자 시퀀스는 단일 ‘a’로 대체됩니다.
3. 공백 정규화: 모든 공백 시퀀스(공백, 탭, 줄바꿈)는 하나의 공백으로 축소됩니다.
4. 기호 보존: 구두점 및 특수 문자(예: :, [, ], /)는 로그 구조를 나타내는 가장 강력한 지표인 경우가 많으므로 보존됩니다.

로그 매핑 접근 방식을 소개합니다. 기본 매핑 패턴은 다음과 같습니다.

• 길이에 상관없이 0-9자리 숫자 ->'0'으로 대체.
• 모든 길이의 텍스트(공백이 있는 알파벳 문자) -> 'a'로 대체.
• 공백, 탭, 줄바꿈 -> 하나의 공간으로 축소.

이 매핑을 통해 로그를 어떻게 변환하는지에 대한 예를 살펴보겠습니다.

그 결과, 다음과 같은 로그 마스크를 얻습니다.

처음 두 로그의 지문을 주목하세요. 타임스탬프, 소스 클래스, 메시지 내용이 다르더라도 접두사(0/0/0 0:0:0 a a.a:)는 동일합니다. 이러한 구조적 정렬을 통해 이러한 로그를 동일한 클러스터에 자동으로 버킷화할 수 있습니다.

하지만 세 번째 로그는 완전히 다른 지문을 생성합니다(0-0-0...). 이를 통해 LLM을 호출하기 전에 첫 번째 그룹과 알고리즘적으로 분리할 수 있습니다.

보너스: ES|QL을 이용한 즉시 구현

Discover에서 이 쿼리를 전달하기만 하면 됩니다.

FROM loghub |
EVAL pattern = REPLACE(REPLACE(REPLACE(REPLACE(raw_message, "[ \t\n]+", " "), "[A-Za-z]+", "a"), "[0-9]+", "0"), "a( a)+", "a") |
STATS total_count = COUNT(), ratio = COUNT() / 2000.0, datasources=VALUES(filename), example=TOP(raw_message, 3, "desc") BY SUBSTRING(pattern, 0, 15) |
SORT total_count DESC |
LIMIT 100

쿼리 분석:

FROM loghub: 원시 로그 데이터를 포함하는 인덱스를 대상으로 합니다.

EVAL 패턴 = …: 핵심 매핑 로직. REPLACE 함수를 연결하여 추상화(예: 숫자를 '0'으로, 텍스트를 'a'로 등)를 수행하고 결과를 '패턴' 필드에 저장합니다.

STATS [column1 =] expression1, … BY SUBSTRING(pattern, 0, 15):

이는 클러스터링 단계입니다. 패턴의 처음 15자를 공유하는 로그를 그룹화하고 그룹당 총 로그 수, 로그 데이터 소스 목록, 패턴 접두사, 3개의 로그 예시와 같은 집계 필드를 만듭니다.

SORT total_count DESC | LIMIT 100 : 가장 빈번한 상위 100개의 로그 패턴을 표시합니다

LogHub의 쿼리 결과는 아래와 같습니다.

시각화 자료에서 볼 수 있듯이, 이 'LLM 없는' 접근 방식은 높은 정확도로 로그를 분할합니다. LogHub 레이블을 기준으로 16개 데이터 소스 중 10개를 완벽하게(>90%) 클러스터링했고, 13개 소스에서는 과반수 클러스터링을 달성했습니다(>60%). 이 모든 결과는 추가적인 데이터 정제, 전처리 또는 미세 조정 없이 얻어졌습니다.

로그 형식 지문은 로그 패턴 분석과 같은 정교한 ML 솔루션에 더해 실용적이고 영향력이 큰 대안을 제공합니다. 로그 관계에 대한 즉각적인 인사이트를 제공하고 대규모 로그 클러스터를 효과적으로 관리할 수 있습니다.

• 원시적인 요소로서의 높은 활용도

ES|QL 구현 덕분에 LFF는 빠른 데이터 진단/시각화를 위한 독립형 도구로, 그리고 대용량 사용 사례를 위한 로그 분석 파이프라인의 구성 요소로 모두 사용할 수 있습니다.

• 유연성

LFF는 쉽게 사용자 정의하고 확장하여 특정 패턴(예: 16진수 및 IP 주소)을 캡처할 수 있습니다.

• 결정론적 안정성

ML 기반 클러스터링 알고리즘과 달리, LFF 로직은 간단하고 결정론적입니다. 새로 들어오는 로그는 기존 로그 클러스터에 소급하여 영향을 미치지 않습니다.

• 성능 및 mMemory

최소한의 메모리만 필요하고, 학습이나 GPU도 필요 없으므로 실시간 고처리량 환경에 적합합니다.

로그 형식 지문과 LLM 결합하기

제안된 하이브리드 아키텍처를 검증하기 위해 각 실험에는 각 데이터 소스에서 무작위로 선택한 20%의 로그 하위 집합이 포함되었습니다. 이러한 제약 조건은 로그가 배치 처리되는 실제 프로덕션 환경을 시뮬레이션한 것으로, 로그가 하나의 거대한 과거 데이터 더미로 처리되는 환경과는 다릅니다.

목표는 LFF가 효과적인 압축 레이어로 작용함을 입증하는 것이었습니다. 또한 엄선된 소규모 샘플로부터 높은 커버리지를 갖는 구문 분석 규칙을 생성하고 이를 전체 데이터 세트에 성공적으로 일반화할 수 있음을 증명하고자 했습니다.

실행 파이프라인

데이터가 LLM에 도달하기 전에 필터링, 클러스터링, 계층화된 샘플링을 적용하는 다단계 파이프라인을 구현했습니다.

1. 2단계 계층적 클러스터링

• 하위 클래스(정확히 일치): 로그는 동일한 지문을 기준으로 집계됩니다. 하나의 하위 클래스에 있는 모든 로그는 정확히 동일한 형식 구조를 공유합니다.
• 이상값 정리. 전체 로그 볼륨의 5% 미만을 차지하는 하위 클래스는 모두 삭제합니다. 이렇게 하면 LLM이 주요 신호에 집중할 수 있고 노이즈나 잘못된 로그에 의해 방해받지 않게 됩니다.
• 메타클래스(접두사 일치): 나머지 하위 클래스는 형식 지문 일치의 첫 N 문자에 의해 메타클래스로 그룹화됩니다. 이 그룹화 전략은 어휘적으로 유사한 형식을 하나의 범주로 효과적으로 분할합니다. 데이터 소스를 알 수 없는 경우 로그 구문 분석에는 N=5를, 로그 분할에는 N=15를 선택했습니다.

2. 계층화된 샘플링. 계층 구조 트리가 구축되면 LLM에 대한 로그 샘플을 구성합니다. 전략적 목표는 분산 범위를 최대화하고 토큰 사용량을 최소화하는 것입니다.

• 더 넓은 메타클래스 내의 각 유효한 하위 클래스에서 대표적인 로그를 선택합니다.
• 너무 많은 하위 클래스의 예외적인 경우를 관리하기 위해 대상 윈도우 크기에 맞게 무작위 다운샘플링을 적용합니다.

3. 규칙 생성 마지막으로, LLM에 각 메타클래스에 대해 제공된 샘플의 모든 로그에 맞는 정규식 구문 분석 규칙을 생성하도록 지시합니다. 본 PoC에서는 GPT-4o 미니 모델을 사용했습니다.

실험 결과 및 관찰

Loghub 데이터 세트에서 구문 분석 정확도 94%, 분할 정확도 91%를 달성했습니다.

위의 혼동 행렬은 로그 분할 결과를 보여줍니다. 세로축은 실제 데이터 소스를 나타내고 가로축은 예측된 데이터 소스를 나타냅니다. 히트맵 강도는 로그 볼륨에 대응하며, 밝은 타일은 더 많은 수를 나타냅니다. 대각선 정렬은 산포가 최소화된 상태에서 모델이 소스 귀속을 매우 정확하게 수행함을 보여줍니다.

성과 벤치마크 인사이트:

• 최적의 기준선: 카테고리당 30–40개 로그 샘플의 컨텍스트 윈도우가 '최적의 지점'으로 입증되었으며, 정규식과 Grok 패턴에서 모두 일관되게 강력한 구문 분을 생성했습니다.
• 입력 최소화: 정규식 패턴에 대해 카테고리당 입력 크기를 10개의 로그로 늘렸을 때 구문 분석 성능이 2%만 저하하는 것을 확인했으며, 이는 다양성 기반 샘플링이 원시 볼륨보다 더 중요하다는 점을 입증합니다.

Jina 모델은 정보 처리, 정리, 검색을 지원하도록 설계된 세 가지 큰 카테고리로 나뉩니다.

• 시맨틱 임베딩 모델
• 모델 순위 재지정
• 소규모 생성형 언어 모델

시맨틱 임베딩 모델

시맨틱 임베딩의 핵심 아이디어는 AI 모델이 입력의 의미적 측면을 고차원 공간의 기하학적 형태로 표현하는 방법을 학습할 수 있다는 것입니다.

시맨틱 임베딩은 고차원 공간에 있는 점(엄밀히 말하면 벡터)으로 생각할 수 있습니다. 임베딩 모델은 일부 디지털 데이터(어떤 것이든 가능하지만 대부분 텍스트나 이미지)를 입력으로 받아 해당 고차원 점의 위치를 일련의 숫자 좌표로 출력하는 신경망입니다. 모델이 제대로 작동한다면 두 시맨틱 임베딩 사이의 거리는 해당 디지털 객체가 동일한 의미를 갖는 정도에 비례합니다.

검색 애플리케이션에서 이것이 얼마나 중요한지 이해하려면 '개'라는 단어와 '고양이'라는 단어에 대한 임베딩을 공간의 점으로 상상해 보세요.

좋은 임베딩 모델은 '고양이'라는 단어에 대해 '개'보다 '고양이'에 훨씬 가까운 임베딩을 생성해야 하며, '개'는 거의 같은 의미이므로 '고양이'보다 '개'에 훨씬 가까운 임베딩을 가져야 합니다.

모델이 다국어인 경우 '고양이'와 '개'의 번역에 대해 동일한 결과를 기대할 수 있습니다.

임베딩 모델은 사물 간 의미의 유사성 또는 유사성을 임베딩 간의 공간적 관계로 변환합니다. 위의 그림은 화면에서 볼 수 있도록 2차원으로만 표현했지만, 모델을 임베드하면 수십에서 수천 개의 차원을 가진 벡터가 만들어집니다. 이를 통해 전체 텍스트의 미묘한 의미를 인코딩할 수 있으며, 수천 단어 이상의 문서에 대해 수백 또는 수천 개의 차원을 가진 공간에 지점을 할당할 수 있습니다.

멀티모달 임베딩

멀티모달 모델은 시맨틱 임베딩의 개념을 텍스트 이외의 것, 특히 이미지로 확장합니다. 사진에 대한 임베딩은 사진에 대한 충실한 설명을 임베딩하는 것과 비슷할 것으로 예상합니다.

시맨틱 임베딩은 다양한 용도를 가지고 있습니다. 무엇보다도 효율적인 분류기를 구축하고, 데이터 클러스터링을 수행하고, 데이터 중복 제거 및 데이터 다양성 조사와 같은 다양한 작업을 수행하는 데 사용할 수 있으며, 이는 모두 수작업으로 관리하기에는 너무 많은 데이터를 다루는 빅데이터 애플리케이션에 중요한 작업입니다.

임베딩의 가장 큰 직접적인 용도는 정보 검색입니다. Elasticsearch는 임베딩을 키로 사용하여 검색 객체를 저장할 수 있습니다. 쿼리는 임베딩 벡터로 변환되고 검색은 쿼리 임베딩에 가장 가까운 키가 있는 저장된 객체를 반환합니다.

전통적인 벡터 기반 검색(때때로 희소 벡터 검색이라고 함)이 문서와 쿼리에서 단어나 메타데이터를 기반으로 한 벡터를 사용하는 반면, 임베딩 기반 검색(또한 밀집 벡터 검색이라고 함)은 단어가 아닌 AI가 평가한 의미를 사용합니다. 따라서 일반적으로 기존 검색 방법보다 훨씬 더 유연하고 정확합니다.

Matryoshka 표현 학습

임베딩의 차원 수와 임베딩에 포함된 숫자의 정밀도는 성능에 상당한 영향을 미칩니다. 매우 높은 차원의 공간과 매우 정밀한 숫자는 매우 상세하고 복잡한 정보를 표현할 수 있지만, 학습과 실행에 더 많은 비용이 드는 더 큰 AI 모델을 필요로 합니다. 벡터를 생성하려면 더 많은 저장 공간이 필요하고 벡터 사이의 거리를 계산하는 데 더 많은 컴퓨팅 사이클이 필요합니다. 시맨틱 임베딩 모델을 사용하는 것은 정밀도와 자원 소비 간의 중요한 절충을 포함합니다.

사용자의 유연성을 극대화하기 위해 Jina 모델은 마트료시카 표현 학습이라는 기법으로 훈련됩니다. 이렇게 하면 모델이 가장 중요한 의미적 구분을 임베딩 벡터의 첫 번째 차원에 미리 로드하므로 상위 차원을 잘라내도 여전히 좋은 성능을 얻을 수 있습니다.

실제로 이는 Jina 모델 사용자가 임베딩에 원하는 차원 수를 선택할 수 있음을 의미합니다. 차원을 적게 선택하면 정밀도가 감소하지만, 성능 저하는 미미합니다. 대부분의 작업에서 Jina 모델의 성능 지표는 임베딩 크기를 50% 줄일 때마다 1~2% 감소하며, 크기가 약 95% 감소할 때까지 이러한 경향이 지속됩니다.

비대칭 검색

시맨틱 유사성은 일반적으로 대칭적으로 측정됩니다. '고양이'와 '개'를 비교할 때 얻는 값은 '개'와 '고양이'를 비교할 때 얻는 값과 동일합니다. 그러나 정보 검색에 임베딩을 사용할 때는 대칭을 깨고 검색 객체를 인코딩하는 방식과 다르게 쿼리를 인코딩하면 더 잘 작동합니다.

이는 임베딩 모델을 훈련하는 방식 때문입니다. 훈련 데이터에는 단어와 같은 동일한 요소가 다양한 맥락에서 나타나는 사례들이 포함되어 있으며, 모델은 요소 간의 맥락적 유사점과 차이점을 비교하여 의미를 학습합니다.

예를 들어 '동물'이라는 단어가 '고양이' 또는 '개'와 같은 문맥에서 많이 나타나지 않으므로 '동물'에 대한 임베딩이 '고양이' 또는 '개'와 특별히 가깝지 않을 수 있습니다.

따라서 '동물'을 검색하면 목표와는 정반대로 고양이와 개에 관한 문서가 검색될 가능성이 줄어듭니다. 따라서 '동물'이 검색 대상일 때와 쿼리일 때를 다르게 인코딩합니다.

비대칭 검색이란 쿼리에 다른 모델을 사용하거나, 저장된 데이터를 한 가지 방식으로 인코딩하고 쿼리를 다른 방식으로 인코딩하도록 임베딩 모델을 특별히 학습시키는 것을 의미합니다.

멀티벡터 임베딩

단일 임베딩은 인덱스 데이터베이스의 기본 프레임워크에 적합하기 때문에 정보 검색에 유용합니다. 즉, 검색 키로 단일 임베딩 벡터를 사용하여 검색 대상 객체를 저장합니다. 사용자가 문서 저장소를 쿼리하면 쿼리가 임베딩 벡터로 변환되고 쿼리 임베딩에 가장 가까운 키(고차원 임베딩 공간에서)를 가진 문서가 후보 일치 항목으로 검색됩니다.

멀티벡터 임베딩은 약간 다르게 작동합니다. 쿼리와 전체 저장된 객체를 나타내는 고정 길이 벡터를 생성하는 대신, 쿼리의 작은 부분을 나타내는 임베딩 시퀀스를 생성합니다. 구성 요소는 일반적으로 텍스트의 경우 토큰 또는 단어이며, 시각적 데이터의 경우 이미지 타일입니다. 이러한 임베딩은 해당 부분의 의미를 그 컨텍스트 내에서 반영합니다.

예를 들어 다음 문장을 생각해 보세요.

• 그녀는 상냥한 마음씨를 가졌습니다.
• 그녀는 마음이 바뀌었습니다.
• 그녀는 심장 마비를 일으켰습니다.

표면적으로는 매우 비슷해 보이지만 멀티벡터 모델은 'heart'의 각 인스턴스에 대해 매우 다른 임베딩을 생성하여 전체 문장의 맥락에서 각각이 어떻게 다른 의미를 갖는지를 표현합니다.

멀티벡터 임베딩을 통해 두 개체를 비교하려면 한 멀티벡터 임베딩의 각 부분을 다른 멀티벡터 임베딩의 각 부분과 비교하고 그 사이의 최소 거리를 합산하는 모따기 거리를 측정하는 경우가 많습니다. 아래에서 설명하는 Jina Rerankers를 포함한 다른 시스템들은 이들을 이들의 유사성을 평가하도록 특별히 훈련된 AI 모델에 입력합니다. 멀티벡터 임베딩은 단일 벡터 임베딩보다 훨씬 더 자세한 정보를 포함하기 때문에 일반적으로 두 접근 방식 모두 단일 벡터 임베딩을 비교하는 것보다 정밀도가 높습니다.

그러나 멀티벡터 임베딩은 색인에 적합하지 않습니다. 다음 섹션에서 설명된 jina-colbert-v2 모델과 같이 순위 재지정 작업에서 자주 사용됩니다.

Jina 임베딩 모델

Jina 임베딩 v4

jina-embeddings-v4는 38억(3.8x10⁹) 매개변수의 다국어 및 멀티모달 임베딩 모델로, 다양한 널리 사용되는 언어의 이미지와 텍스트를 지원합니다. 시각적 지식과 언어 지식을 활용하여 두 작업의 성능을 향상시키는 새로운 아키텍처를 사용하여 이미지 검색, 특히 시각적 문서 검색에서 탁월한 성능을 발휘합니다. 이는 차트, 슬라이드, 맵, 스크린샷, 페이지 스캔 및 다이어그램과 같은 이미지를 처리한다는 것을 의미합니다. 이러한 이미지는 일반적인 종류의 이미지로, 종종 중요한 내장 텍스트가 포함되어 있으며, 실제 장면의 사진으로 훈련된 컴퓨터 비전 모델의 범위를 벗어납니다.

컴팩트한 로우랭크 적응(LoRA) 어댑터를 사용하여 여러 가지 작업에 맞게 이 모델을 최적화했습니다. 이를 통해 메모리나 프로세싱의 추가 비용을 최소화하면서 여러 작업의 성능 저하 없이 단일 모델을 여러 작업에 특화하도록 훈련할 수 있습니다.

주요 기능은 다음과 같습니다:

• 시각적 문서 검색의 최첨단 성능과 함께 다국어 텍스트 및 일반 이미지 성능은 훨씬 더 큰 모델을 능가합니다.
• 큰 입력 컨텍스트 크기 지원: 32,768토큰은 대략 두 줄짜리 영어 텍스트 80페이지에 해당하며, 20메가픽셀은 4,500 x 4,500픽셀 이미지에 해당합니다.
• 임베딩 크기는 최대 2048개에서 최소 128개까지 사용자가 선택할 수 있습니다. 경험적으로 이 임계값 이하에서는 성능이 급격히 저하되는 것으로 나타났습니다.
• 단일 임베딩과 멀티벡터 임베딩을 모두 지원합니다. 텍스트의 경우, 멀티벡터 출력은 각 입력 토큰에 대해 128차원 임베딩 하나로 구성됩니다. 이미지의 경우, 이미지를 커버하는 데 필요한 각 28x28 픽셀 타일에 대해 하나의 128차원 임베딩을 생성합니다.
• 비대칭 검색을 위한 최적화는 특별히 이를 위해 훈련된 LoRA 어댑터 한 쌍을 통해 이루어집니다.
• 시맨틱 유사도 계산에 최적화된 LoRA 어댑터입니다.
• LoRA 어댑터를 통해서도 컴퓨터 프로그래밍 언어 및 IT 프레임워크를 특별히 지원합니다.

광범위한 일반 검색, 자연어 이해 및 AI 분석 작업을 위한 범용 다목적 도구로 사용할 수 있도록 jina-embeddings-v4를 개발했습니다. 기능에 비해 비교적 작은 모델이지만 배포하는 데 상당한 리소스가 필요하며 클라우드 API를 통해 사용하거나 대용량 환경에서 사용하기에 가장 적합합니다.

Jina 임베딩 v3

jina-embeddings-v3는 6억 개 미만의 매개변수를 가진 소규모 고성능 다국어 텍스트 전용 임베딩 모델입니다. 최대 8192개의 텍스트 입력 토큰을 지원하며, 기본 1024개부터 최대 64개까지 사용자가 선택한 크기의 단일 벡터 임베딩을 출력합니다.

정보 검색 및 의미적 유사성뿐만 아니라 감정 분석 및 콘텐츠 조정과 같은 분류 작업, 뉴스 집계 및 추천과 같은 클러스터링 작업 등 다양한 텍스트 작업에 대해 jina-embeddings-v3를 학습시켰습니다. jina-embeddings-v4와 마찬가지로 이 모델은 다음 사용 범주에 특화된 LoRA 어댑터를 제공합니다.

• 비대칭 검색
• 의미적 유사성
• 분류
• 클러스터링

jina-embeddings-v3 입력 컨텍스트 크기가 크게 줄어든 jina-embeddings-v4 모델보다 훨씬 작지만 운영 비용은 더 적게 듭니다. 그럼에도 불구하고 텍스트에만 해당되긴 하지만 성능 경쟁력이 매우 뛰어나고 많은 사용 사례에서 더 나은 선택입니다.

Jina 코드 임베딩

Jina의 특수 코드 임베딩 모델인 jina-code-embeddings(0.5b 및 1.5b)는 15가지 프로그래밍 체계와 프레임워크, 그리고 컴퓨팅 및 정보기술 관련 영어 텍스트를 지원합니다. 각각 5억(0.5x10⁹) 및 15억(1.5x10⁹) 크기의 소규모 모델입니다. 두 모델 모두 최대 32,768개의 토큰 입력 컨텍스트 크기를 지원하며, 작은 모델의 경우 896개에서 64개까지, 큰 모델의 경우 1536개에서 128개까지 사용자가 출력 임베딩 크기를 선택할 수 있습니다.

이러한 모델은 접두사 튜닝을 사용하여 LoRA 어댑터 대신 5가지 작업별 특화를 위한 비대칭 검색을 지원합니다.

• 코드-코드. 프로그래밍 언어 전반에서 유사한 코드를 검색합니다. 이는 코드 정렬, 코드 중복 제거, 이식 및 리팩토링 지원에 사용됩니다.
• 자연어-코드. 코드를 검색하여 자연어 쿼리, 댓글, 설명 및 문서와 일치시킵니다.
• 코드-자연어.코드를 문서 또는 기타 자연어 텍스트와 일치시킵니다.
• 코드-코드 완성. 관련 코드를 제안하여 기존 코드를 완료하거나 향상시킵니다.
• 기술 관련 Q&A. 정보 기술에 관한 질문에 대한 자연어 답변을 식별합니다. 이는 기술 지원 사용 사례에 이상적입니다.

이러한 모델은 컴퓨터 문서화 및 프로그래밍 자료와 관련된 작업에서 상대적으로 적은 컴퓨팅 비용으로 우수한 성능을 제공합니다. 개발 환경 및 코드 어시스턴트에 통합하는 데 적합합니다.

Jina ColBERT v2

jina-colbert-v2는 5억 6천만 개의 매개변수를 가진 멀티벡터 텍스트 임베딩 모델입니다. 다국어 지원, 89개 언어의 자료를 사용하여 학습되었으며 다양한 임베딩 크기와 비대칭 검색을 지원합니다.

앞서 언급했듯이, 멀티벡터 임베딩은 색인하는 데에는 적합하지 않지만 다른 검색 전략의 결과 정확도를 높이는 데 매우 유용합니다. jina-colbert-v2를 사용하여 멀티벡터 임베딩을 미리 계산한 다음 쿼리 시 검색 후보의 순위를 재조정하는 데 사용할 수 있습니다. 이 접근 방식은 다음 섹션의 재순위 모델 중 하나를 사용하는 것보다 정확도는 떨어지지만 모든 쿼리와 후보 일치에 대해 전체 AI 모델을 호출하는 대신 저장된 멀티벡터 임베딩을 비교하기 때문에 훨씬 더 효율적입니다. 이는 순위 재지정 모델을 사용할 때의 지연 시간과 계산 부하가 너무 큰 사용 사례나 비교할 후보의 수가 순위 재지정 모델에 너무 많은 경우에 이상적으로 적합합니다.

이 모델은 입력 토큰당 하나씩 일련의 임베딩을 출력하며, 사용자는 128차원, 96차원 또는 64차원 임베딩의 토큰 임베딩을 선택할 수 있습니다. 후보 텍스트 매칭은 8,192개 토큰으로 제한됩니다. 쿼리는 비대칭적으로 인코딩되므로, 사용자는 텍스트가 쿼리인지 후보 일치인지 지정해야 하며, 쿼리 수를 32개의 토큰으로 제한해야 합니다.

Jina CLIP v2

jina-clip-v2는 9억 개의 매개변수를 가진 멀티모달 임베딩 모델로, 텍스트가 이미지의 내용을 설명할 경우 텍스트와 이미지가 서로 가까운 임베딩을 생성하도록 학습되었습니다. 주요 용도는 텍스처 쿼리를 기반으로 이미지를 검색하는 것이지만, 텍스트 전용 모델로도 고성능을 발휘하여 사용자 비용을 절감할 수 있습니다. 텍스트-텍스트 및 텍스트-이미지 검색을 위해 별도의 모델이 필요하지 않기 때문입니다.

이 모델은 8,192개의 토큰으로 구성된 텍스트 입력 컨텍스트를 지원하며, 이미지는 임베딩을 생성하기 전에 512x512 픽셀로 크기가 조정됩니다.

대조적 언어-이미지 사전 훈련(CLIP) 아키텍처는 훈련 및 운영이 쉽고 매우 컴팩트한 모델을 생성할 수 있지만, 몇 가지 근본적인 한계가 있습니다. 그들은 한 매체에서 얻은 지식을 다른 매체에서의 성능 향상에 사용할 수 없습니다. 한 매체에서 다른 매체로 사용하여 성능을 향상시킬 수 없습니다. 따라서 '개'와 '고양이'라는 단어가 '자동차'보다 의미상 서로 가깝다는 것은 알 수 있지만, 개 그림과 고양이 그림이 자동차 그림보다 더 관련이 있다는 것을 반드시 알지는 못합니다.

또한 양식 격차라는 문제도 있습니다. 개에 대한 텍스트 임베딩은 개 사진 임베딩보다 고양이에 대한 텍스트 임베딩에 더 가깝게 느껴질 가능성이 높습니다. 이러한 제한 때문에 CLIP을 텍스트-이미지 검색 모델 또는 텍스트 전용 모델로 사용하는 것이 좋지만, 단일 쿼리에서 둘을 혼합하지 않는 것이 좋습니다.

모델 순위 재지정

순위 재지정 모델은 하나 이상의 후보 일치 항목과 쿼리를 모델에 입력으로 받아 이를 직접 비교하여 훨씬 더 높은 정밀도의 일치 항목을 생성합니다.

원칙적으로, 각 쿼리를 저장된 각 문서와 비교하여 정보 검색을 위해 직접 순위 재지정 도구를 사용할 수 있지만, 이는 매우 계산 비용이 많이 들고 가장 작은 컬렉션을 제외하고는 비실용적입니다. 결과적으로, 순위 재지정 도구는 임베딩 기반 검색이나 다른 검색 알고리즘과 같은 다른 방법을 통해 찾은 비교적 짧은 후보 목록을 평가하는 데 사용되는 경향이 있습니다. 순위 재지정 모델은 하이브리드 및 연합 검색 체계에 이상적으로 적합합니다. 여기서 검색을 수행한다는 것은 쿼리가 별도의 검색 시스템으로 전송되어 각각 고유한 데이터 세트를 가지고 각기 다른 결과를 반환할 수 있음을 의미합니다. 다양한 결과를 하나의 고품질 결과로 병합하는 데 매우 효과적입니다.

임베딩 기반 검색은 저장된 모든 데이터를 재색인하고 검색 결과에 대한 사용자 기대치를 변경해야 하므로 상당한 노력이 필요합니다. 기존 검색 체계에 리랭커를 추가하면 AI의 많은 이점을 추가할 수 있으며, 전체 검색 솔루션을 다시 설계할 필요 없이 이를 달성할 수 있습니다.

Jina 순위 재지정 모델

Jina 순위 재지정 m0

jina-reranker-m0는 24억(2.4x10⁹)개의 매개변수를 가진 다중 모드 순위 재지정 도구로, 텍스트 쿼리와 텍스트 및/또는 이미지로 구성된 후보 매치를 지원합니다. 이 모델은 시각적 문서 검색의 선도적 모델로, PDF 저장소, 텍스트 스캔, 스크린샷 및 텍스트 또는 반구조화된 정보를 포함한 기타 컴퓨터 생성 또는 수정 이미지뿐만 아니라 텍스트 문서와 이미지로 구성된 혼합 데이터에도 이상적인 솔루션입니다.

이 모델은 단일 쿼리와 일치하는 후보를 입력받아 점수를 반환합니다. 동일한 쿼리를 다른 후보와 함께 사용하면 점수를 비교하여 순위를 매기는 데 사용할 수 있습니다. 쿼리 텍스트와 후보 텍스트 또는 이미지를 포함하여 최대 10,240개 토큰의 총 입력 크기를 지원합니다. 이미지를 덮는 데 필요한 28x28 픽셀 타일 하나하나가 입력 크기 계산을 위한 토큰으로 간주됩니다.

Jina 순위 재지정 v3

jina-reranker-v3는 비슷한 크기의 모델을 위한 최첨단 성능을 갖춘 6억 개의 매개변수 텍스트 순위 재지정 도구입니다. jina-reranker-m0와 달리, 단일 쿼리와 최대 64개의 후보 매칭 목록을 받아 순위 순서를 반환합니다. 쿼리와 모든 텍스트 후보를 포함하여 131,000개의 토큰으로 구성된 입력 컨텍스트가 있습니다.

Jina 순위 재지정 v2

jina-reranker-v2-base-multilingual은 함수 호출 및 SQL 쿼리를 지원하도록 설계된 추가 기능을 갖춘 매우 컴팩트한 범용 순위 재지정 도구입니다. 3억 개 미만의 매개변수를 포함하며, 빠르고 효율적이며 정확한 다국어 텍스트 순위 재지정을 제공하며, 텍스트 쿼리에 맞는 SQL 테이블과 외부 함수 선택 지원도 추가하여 에이전트 사용 사례에 적합합니다.

소규모 생성형 언어 모델

생성형 언어 모델은 텍스트 또는 멀티미디어 입력을 받아 텍스트 출력으로 응답하는 OpenAI의 ChatGPT, Google Gemini, Anthropic의 Claude와 같은 모델입니다. 대규모 언어 모델(LLM)과 소규모 언어 모델(SLM)을 구분하는 명확한 경계는 없지만, 최고급 LLM을 개발, 운영 및 사용하는 데 따르는 실질적인 문제는 잘 알려져 있습니다. 가장 잘 알려진 것들은 공개적으로 배포되지 않았기 때문에 우리는 그 크기를 추정할 수만 있지만, ChatGPT, Gemini 및 Claude는 1~3조(1~3x10¹²) 매개변수 범위 내에 있을 것으로 예상됩니다.

이러한 모델을 실행하는 것은, 심지어 공개적으로 이용 가능하더라도, 기존 하드웨어의 범위를 훨씬 넘어서며, 방대한 병렬 어레이로 구성된 최첨단 칩을 필요로 합니다. LLM에는 유료 API를 통해 액세스할 수 있지만, 이는 상당한 비용이 발생하고 높은 대기 시간을 가지며 데이터 보호, 디지털 주권 및 클라우드 재환원에 대한 요구 사항과 일치하기 어렵습니다. 또한 이 정도 규모의 모델을 교육하고 사용자 지정하는 데 드는 비용도 상당할 수 있습니다.

그 결과, 대형 LLM의 모든 기능은 부족할 수 있지만 저렴한 비용으로 특정 종류의 작업을 잘 수행할 수 있는 소규모 모델을 개발하기 위해 많은 연구가 진행되었습니다. 기업은 보통 특정 문제를 해결하기 위해 소프트웨어를 배포하며, AI 소프트웨어도 다르지 않습니다. 따라서 SLM 기반 솔루션이 LLM 기반 솔루션보다 나은 경우가 많습니다. 일반적으로 상용 하드웨어에서 실행할 수 있고, 더 빠르며 실행에 필요한 에너지를 덜 소비하고, 훨씬 더 쉽게 사용자 정의할 수 있습니다.

AI를 실용적인 검색 솔루션에 가장 효과적으로 도입할 수 있는 방법에 집중하면서 Jina의 SLM 제품군은 성장하고 있습니다.

Jina SLMs

ReaderLM v2

ReaderLM-v2는 사용자가 제공한 JSON 스키마와 자연어 명령어에 따라 HTML을 Markdown 또는 JSON으로 변환하는 생성형 언어 모델입니다.

데이터 전처리 및 정규화는 디지털 데이터에 대한 효과적인 검색 솔루션을 개발하는 데 필수적인 부분이지만, 실제 세계의 데이터, 특히 웹에서 파생된 정보는 종종 혼란스럽고, 단순한 변환 전략은 매우 취약한 것으로 드러나는 경우가 많습니다. 대신, ReaderLM-v2 웹페이지의 DOM 트리 덤프의 혼란을 이해하고 유용한 요소를 강력하게 식별할 수 있는 지능형 AI 모델 솔루션을 제공합니다.

15억(1.5x10⁹)개의 매개변수로, 최첨단 LLM보다 세 자릿수 차이로 작지만 이 특정 작업에서는 동등한 수준의 성능을 발휘합니다.

Jina VLM

jina-vlm은 이미지에 대한 자연어 질문에 답하도록 훈련된 24억 (2.4x10⁹)개의 매개변수 생성형 언어 모델입니다. 그것은 스캔, 스크린샷, 슬라이드, 다이어그램 및 유사한 비자연적 이미지 데이터에 대한 질문에 답변하는 시각적 문서 분석을 매우 강력하게 지원합니다.

그 예는 다음과 같습니다.

이미지 속 텍스트를 읽는 데도 매우 능숙합니다.

하지만 jina-vlm의 진정한 강점은 정보성 이미지와 인공 이미지의 콘텐츠를 이해하는 것입니다.

또는:

jina-vlm 자동 캡션 생성, 제품 설명, 이미지 대체 텍스트, 시각 장애인을 위한 접근성 애플리케이션에 적합합니다. 또한 검색 증강 생성(RAG) 시스템이 시각 정보를 사용하고 AI 에이전트가 사람의 도움 없이 이미지를 처리할 수 있는 가능성을 열어줍니다.

Elastic Agent Builder를 사용하면 데이터 기반 AI 에이전트를 쉽게 구축할 수 있습니다. 이 블로그 게시물에서 그 방법을 알려드리겠습니다. Elastic에 저장된 데이터에 액세스하는 MCP 도구로 에이전트를 생성하는 데 필요한 모든 단계를 살펴본 후, Strands Agents SDK와 그의 Agent2Agent(A2A) 기능을 사용하여 에이전트를 운영해 보겠습니다. Strands Agents SDK는 멀티 에이전트 AI 개발 플랫폼으로, 최소한의 코드만으로 원하는 결과를 얻을 수 있는 에이전틱 앱을 구축할 수 있습니다.

RPS+ 게임을 플레이하는 AI 에이전트를 만들어 보세요. RPS+는 기존 가위바위보 게임에 새로운 변형을 더한 게임으로, 플레이어에게 몇 가지 추가 선택지를 제공합니다.

필수 구성 요소

이 블로그 게시물의 단계를 따라 진행하려면 다음과 같은 준비 사항이 필요합니다.

• 로컬 컴퓨터에서 실행 가능한 텍스트 편집기
  • 이 블로그 게시물의 예제 지침에는 Visual Studio Code를 사용합니다.
• 로컬 컴퓨터에 설치된 Python 3.10 이상

서버리스 프로젝트 만들기

우선 Elastic Agent Builder가 포함된 Elasticsearch Serverless 프로젝트가 필요합니다.

cloud.elastic.co로 이동해 새로운 Elasticsearch Serverless 프로젝트를 생성하세요.

인덱스 생성 및 데이터 추가

다음으로 Elasticsearch 프로젝트에 몇 가지 데이터를 추가해 보겠습니다. Developer Tools를 열고 명령어를 실행하여, 새 인덱스를 만들고 일부 데이터를 삽입할 수 있습니다. 최상단 탐색 메뉴에서 Developer Tools를 선택하세요.

다음 PUT 명령어를 복사하고 Developer Tools 콘솔의 요청 입력 영역에 붙여넣으세요. 이 명령문은 “game-docs”라는 이름의 Elasticsearch 인덱스를 생성합니다.

PUT /game-docs
{
  "mappings": {
    "properties": {
      "title": { "type": "text" },
      "content": { 
        "type": "text"
      },
      "filename": { "type": "keyword" },
      "last_modified": { "type": "date" }
    }
  }
}

Developer Tools에서 해당 명령문 오른쪽에 표시되는 Send request(요청 전송) 버튼을 클릭하세요. Developer Tools의 응답 영역에서 game-docs 인덱스가 생성되었음을 확인하는 알림이 표시될 겁니다.

game-docs라는 이름의 인덱스는 현재 만들고 있는 게임의 데이터를 저장하기에 좋은 장소입니다. 그럼 rps+-md라는 이름의 문서를 이 인덱스에 추가하여, 게임에 필요한 모든 데이터를 저장해 보겠습니다. 다음 PUT 명령어를 복사하여 Developer Tools 콘솔에 붙여넣으세요.

PUT /game-docs/_doc/rps+-md
{
  "title": "Rock Paper Scissors +",
  "content": "
# Game Name
RPS+

# Starting Prompt
Let's play RPS+ !
---
What do you choose?

# Game Objects
1. Rock 🪨 👊
2. Paper 📜 🖐
3. Scissors ✄ ✌️
4. Light ☼ 👍
5. Dark Energy ☄ 🫱

# Judgement of Victory
* Rock beats Scissors
  * because rocks break scissors
* Paper beats Rock
  * because paper covers rock
* Scissors beat Paper
  * because scissors cut paper
* Rock beats Light
  * because you can build a rock structure to block out light
* Paper beats Light
  * because knowledge stored in files and paper books helps us understand light
* Light beats Dark Energy
  * because light enables humans to lighten up and laugh in the face of dark energy as it causes the eventual heat death of the universe
* Light beats Scissors
  * because light is needed to use scissors safely
* Dark Energy beats Rock
  * because dark energy rocks more than rocks. It rocks rocks and everything else in its expansion of the universe
* Dark Energy beats Paper
  * because humans, with their knowledge stored in files and paper books, can't explain dark energy 
* Scissors beat Dark Energy
  * because a human running with scissors is darker than dark energy

# Invalid Input
I was hoping for an worthy opponent
  - but alas it appears that time has past
  - but alas there's little time for your todo list when [todo:fix this] is so vast

# Cancel Game
The future belongs to the bold. Goodbye..
",
  "filename": "RPS+.md",
  "last_modified": "2025-11-25T12:00:00Z"
}

해당 명령문 옆에 있는 Send request(요청 전송) 버튼을 클릭하여 실행하고 rps+-md 문서를 game-docs 인덱스에 추가하세요.

이제 쿼리할 데이터가 준비되었습니다. Agent Builder를 사용하면 이 과정이 그 어느 때보다 간단해집니다.

최상단 탐색 메뉴에서 Agents(에이전트)를 선택하세요.

그런 다음 기본 Elastic AI 에이전트에게 "What data do I have?(내가 가진 데이터는 무엇인가요?)"라고 묻기만 하면 됩니다.

Elastic AI 에이전트는 데이터를 평가하고 현재 보유한 데이터에 대한 간결한 설명을 제공합니다.

도구 만들기

Elastic에 데이터가 준비되었으니 이제 활용해 보겠습니다. Agent Builder는 에이전트가 작업에 필요한 올바른 컨텍스트를 갖출 수 있도록 데이터에 접근하게 도와주는 MCP 도구를 생성하는 기능을 내장하고 있습니다. 게임 데이터를 조회하는 간단한 도구를 만들어 보겠습니다.

Agent Builder 작업 메뉴를 클릭하세요.

메뉴 옵션에서 View all tools(모든 도구 보기)를 선택하세요.

+ New Tool(새 도구)을 클릭하세요.

Create Tool(도구 생성) 양식에서 도구 유형으로 ES|QL을 선택하고 다음 값을 입력하세요.

Tool ID(도구 ID)에 다음을 입력하세요.

example.get_game_docs

Description(설명)에 다음을 입력하세요.

Get RPS+ doc from Elasticsearch game-docs index.

Configuration(구성)의 경우 ES|QL 쿼리 텍스트 영역에 다음 쿼리를 입력하세요.

FROM game-docs | WHERE filename == "RPS+.md"

완성된 Create tool(도구 생성) 양식은 다음과 같아야 합니다. Save(저장)를 클릭하여 도구를 만드세요.

이제 새로운 도구가 준비되었습니다. 도구는 단순히 보관해 두기보다는 가치 있게 활용해야겠죠. 새로 만든 사용자 지정 도구를 사용할 수 있는 에이전트를 만들어 보겠습니다.

에이전트를 생성하고 도구를 할당하기

Agent Builder를 사용하면 매우 간단하게 에이전트를 만들 수 있습니다. 몇 가지 세부 정보와 함께 에이전트 지침을 입력하기만 하면 됩니다. 이제 에이전트를 만들어보겠습니다.

Manage agents(에이전트 관리)를 클릭하세요.

+ New agent(새 에이전트)를 클릭하세요.

다음 정보를 New Agent(새 에이전트) 양식에 입력하세요.

Agent ID(에이전트 ID)에 아래 텍스트를 입력하세요.

rps_plus_agent

Custom Instructions(사용자 지정 지침) 텍스트 영역에 다음 지침을 입력하세요.

When prompted, if the prompt contains an integer, then select the corresponding numbered item in the list of "Game Objects" from your documents. Otherwise select a random game object. This is your chosen game object for a single round of the game.

# General Game Rules
* 2 players
    - the user: the person playing the game
    - you: the agent playing the game and serving as the game master
* Each player chooses a game object which will be compared and cause them to tie, win or lose.

# Start the game
1. This is the way each new game always starts. You make the first line of your response only the name of your chosen game object. 

2. The remainder of your response should be the "Starting Prompt" text from your documents and generate a list of "Game Objects" for the person playing the game to choose a game object from.  

# End of Game: The game ends in one of the following three outcomes:
1. Invalid Input: If the player responds with an invalid game object choice, respond with variations of the "Invalid Input" text from your documents and then end the game.

2. Tie: The game ends in a tie if the user chooses the same game object as your game object choice.

3. Win or Lose: The game winner is decided based on the "Judgement of Victory" conditions from your documents. Compare the user's game object choice and your game object choice and determine who chose the winning game object.

# Game conclusion
Respond with a declaration of the winner of the game by outputting the corresponding text in the "Judgement of Victory" section of your documents.

Display name(표시 이름)에 아래 텍스트를 입력하세요.

RPS+ Agent

Display description(표시 설명)에 아리 텍스트를 입력하세요.

An agent that plays the game RPS+

Tools(도구) 탭을 클릭하여 이전에 만든 사용자 지정 도구를 에이전트에 제공하세요.

앞서 만든 example.get_game_docs 도구만 선택하세요.

Save(저장)를 클릭하여 새 에이전트를 만드세요.

새 에이전트를 테스트해 보겠습니다. 에이전트 목록에서 원하는 에이전트와 채팅을 시작할 수 있는 편리한 링크가 있습니다.

"start game(게임 시작)"을 입력하기만 하면 게임이 시작됩니다. 잘 작동하는군요.

에이전트의 응답 상단에 게임 개체 선택 항목이 표시되는 것을 볼 수 있습니다. 이를 통해 에이전트의 선택을 확인하고 게임이 예상대로 작동하는지 확인할 수 있습니다. 하지만 상대방의 선택을 미리 알면 가위바위보 게임이 재미있지는 않습니다. 게임을 최종 형태로 다듬고 완성도를 높이기 위해 코드로 에이전트를 제어할 수 있는 에이전트 오케스트레이션 플랫폼을 사용할 수 있습니다.

이제 Strands Agents SDK가 등장합니다.

Strands Agents SDK

새로운 에이전트 개발 프레임워크를 사용해 보고 싶으시다면, Strands Agents SDK가 시도해 볼 만한 가치가 있습니다. Strands Agents SDK는 AWS에서 오픈 소스 Python 구현으로 출시되었으며(2025년 5월), 이제 Typescript 버전도 제공됩니다.

Python에서 Strands Agents SDK 시작하기

코딩 준비를 시작해 보죠. 이제 Strands Agents를 사용해 A2A 프로토콜로 RPS+ 에이전트를 제어하는 예제 앱을 복제하고 실행하는 과정을 빠르게 살펴보겠습니다. 플레이어가 선택을 한 후에 에이전트의 선택이 공개되도록 RPS+ 게임을 좀 더 세밀하게 조정해 보겠습니다. 결국 추측과 예상치 못한 결과가 바로 가위바위보와 같은 게임을 재미있게 만드는 요소이기 때문입니다.

로컬 컴퓨터에서 Visual Studio Code를 열고 새 터미널을 여세요.

새로 열린 터미널에서 다음 명령어를 실행해 Elasticsearch Labs 리포지토리를 복제하세요.

git clone https://github.com/elastic/elasticsearch-labs

다음 cd 명령어를 실행하여 elasticsearch-labs 디렉토리로 이동하세요.

cd elasticsearch-labs

이제 다음 명령어를 실행하여 Visual Studio Code에서 리포지토리를 여세요.

code .

Visual Studio 파일 탐색기에서 supporting-blog-content와 agent-builder-a2a-strands-agents 폴더를 펼친 다음 elastic_agent_builder_a2a_rps+.py 파일을 여세요. Visual Studio Code에서 파일을 열면 다음과 같이 보입니다.

다음은 텍스트 편집기에서 볼 수 있는 elastic_agent_builder_a2a_rps+.py 내용입니다:

import asyncio
from dotenv import load_dotenv
from uuid import uuid4
import httpx
import os
import random
from a2a.client import A2ACardResolver, ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

DEFAULT_TIMEOUT = 60  # set request timeout to 1 minute


def create_message(*, role: Role = Role.user, text: str, context_id=None) -> Message:
    return Message(
        kind="message",
        role="user",
        parts=[Part(TextPart(kind="text", text=text))],
        message_id=uuid4().hex,
        context_id=context_id,
    )


async def main():
    load_dotenv()
    a2a_agent_host = os.getenv("ES_AGENT_URL")
    a2a_agent_key = os.getenv("ES_API_KEY")
    custom_headers = {"Authorization": f"ApiKey {a2a_agent_key}"}

    async with httpx.AsyncClient(
        timeout=DEFAULT_TIMEOUT, headers=custom_headers
    ) as httpx_client:
        # Get agent card
        resolver = A2ACardResolver(httpx_client=httpx_client, base_url=a2a_agent_host)
        agent_card = await resolver.get_agent_card(
            relative_card_path="/rps_plus_agent.json"
        )
        # Create client using factory
        config = ClientConfig(
            httpx_client=httpx_client,
            streaming=True,
        )
        factory = ClientFactory(config)
        client = factory.create(agent_card)
        # Use the client to communicate with the agent
        print("\nSending 'start game' message to Elastic A2A agent...")
        random_game_object = random.randint(1, 5)
        msg = create_message(text=f"start with game object {random_game_object}")
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                context_id = event.context_id
                response_complete = event.parts[0].root.text
                # Get agent choice from the first line of the response
                parsed_response = response_complete.split("\n", 1)
                agent_choice = parsed_response[0]
                print(parsed_response[1])
        # User choice sent for game results from the agent
        prompt = input("Your Choice  : ")
        msg = create_message(text=prompt, context_id=context_id)
        async for event in client.send_message(msg):
            if isinstance(event, Message):
                print(f"Agent Choice : {agent_choice}")
                print(event.parts[0].root.text)


if __name__ == "__main__":
    asyncio.run(main())

이 코드에서 어떤 일이 일어나고 있는지 살펴보도록 하겠습니다. main() 메서드에서 시작하여, 코드는 에이전트 URL과 API 키에 대한 환경 변수에 접근하는 것으로 시작합니다. 그런 다음 이러한 값을 사용하여 에이전트의 에이전트 카드를 가져오는 데 사용할 수 있는 httpx client를 만듭니다. 그런 다음 클라이언트는 에이전트 카드 세부 정보를 사용하여 '게임 시작' 요청을 에이전트에게 보냅니다. 여기서 한 가지 흥미로운 점은 "start game" 요청의 일부로 random_game_object 값을 포함한다는 점입니다. 이 값은 Python 표준 라이브러리의 random 모듈을 사용하여 생성된 임의의 숫자입니다. 이렇게 하는 이유는 AI 에이전트를 가능하게 하는 강력한 LLM들이 무작위성에 능숙하지 않다는 것이 밝혀졌기 때문입니다. 하지만 걱정 마세요. Python이 해결해 주니까요.

이어서 코드 설명을 계속하자면, 에이전트가 "start game" 요청에 응답한 후, 코드가 에이전트의 게임 객체 선택을 추출하여 agent_choice 변수에 저장합니다. 나머지 응답 내용은 최종 사용자에게 텍스트로 표시됩니다. 그러면 사용자는 게임 객체를 선택하라는 메시지를 받게 되며, 해당 입력은 에이전트로 전송됩니다. 그런 다음 코드는 에이전트의 게임 객체 선택과 함께 게임 결과에 대한 에이전트의 최종 결정을 표시합니다.

에이전트 URL과 API 키를 환경 변수로 설정하기

예제 앱이 로컬 컴퓨터에서 실행되므로 Agent Builder 에이전트와 통신하기 위해서는 에이전트의 A2A URL과 API 키를 Strands Agents SDK에 제공해야 합니다. 예제 앱은 .env라는 파일을 사용하여 이러한 값을 저장합니다.

env.example 파일의 복사본을 만들고 새 파일 이름을 .env로 지정하세요.

Elastic Agent Builder로 돌아가서 필요한 두 가지 값을 모두 얻을 수 있습니다.

페이지 오른쪽 상단의 Agent Builder 작업 메뉴에서 View all tools(모든 도구 보기)를 선택하세요.

Tools(도구) 페이지 상단의 MCP Server 드롭다운을 클릭하고 Copy MCP Server URL(MCP 서버 URL 복사)를 선택하세요.

MCP Server URL을 .env 파일에 붙여넣으세요. <YOUR-ELASTIC-AGENT-BUILDER-URL> 자리 표시자 값은 이 URL로 대체됩니다. 이제 URL을 한 가지 수정해야 합니다. 끝 부분의 텍스트 “mcp”를 “a2a”로 바꿔야 하는데, 이는 A2A 프로토콜이 Agent Strands SDK가 Elastic Agent Builder에서 실행 중인 에이전트와 통신하는 데 사용되기 때문입니다.

편집된 URL은 다음과 같이 표시될 것입니다.

https://rps-game-project-12345a.kb.us-east-1.aws.elastic.cloud/api/agent_builder/a2a

Elastic Cloud에 있는 동안 얻어야 하는 또 다른 값은 API 키입니다. 최상단 탐색 메뉴에서 Elasticsearch를 클릭하세요.

Copy API Key(API 키 복사) 버튼을 클릭해 API 키를 복사하세요.

이제 Visual Studio Code로 돌아가 .env 파일에 API 키를 붙여넣어 <YOUR-ELASTIC-API-KEY> 자리 표시자 텍스트를 대체하세요. .env 파일은 다음과 같이 표시될 것입니다.

예제 앱 실행하기

Visual Studio Code에서 새 터미널을 여세요.

터미널에서 다음 cd 명령어를 실행하여 시작하세요.

cd elasticsearch-labs/supporting-blog-content/agent-builder-a2a-strands-agents

다음 명령어를 실행하여 Python 가상 환경을 생성하세요.

python -m venv .venv

사용 중인 컴퓨터의 운영 체제에 따라 다음 명령어를 실행해 가상 환경을 활성화하세요.

• macOS/Linux

source .venv/bin/activate

• Windows

.venv\Scripts\activate

이 예제 앱은 Strands Agents SDK를 사용하며, 이제 SDK를 설치할 차례입니다. 다음 명령어를 실행하여 Strands Agents SDK와 필요한 모든 Python 라이브러리 종속성을 설치하세요.

pip install -r requirements.txt

이제 실행 준비를 끝내고 카운트다운을 시작할 시간입니다. 이 앱을 시작할 준비가 되었으니, 뒤로 물러나세요. 다음 명령어를 사용하여 실행해 보겠습니다.

python elastic_agent_builder_a2a_rps+.py

이제 RPS+ 게임을 즐겨보세요. 정말 수고하셨습니다. 행운을 빕니다!

관련성 있는 컨텍스트를 활용해 AI 앱을 구축하기

이제 AI 에이전트를 구축할 수 있는 기술을 갖추게 되었습니다. 또한 Strands Agents SDK와 같은 에이전트 개발 프레임워크에서 A2A를 통해 Elastic Agent Builder 에이전트를 사용하는 것이 얼마나 쉬운지도 확인했습니다. Elastic을 사용하여 사용자 지정 데이터의 관련 컨텍스트와 연결된 AI 에이전트를 만들어 보세요.

최근 Elastic은 Google MCP Toolbox for Databases 오픈소스 프로젝트에 Elasticsearch를 데이터베이스로 사용할 수 있는 지원 기능을 추가했습니다.

이 새로운 기능을 통해 Google MCP Toolbox로 Elasticsearch에 연결하고 데이터와 직접 "대화하듯" 상호작용할 수 있습니다.

Elasticsearch

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

curl -fsSL https://elastic.co/start-local | sh

이 명령을 실행하면 컴퓨터에 Elasticsearch와 Kibana가 설치되고 Google MCP Toolbox 설정에 사용할 API 키가 생성됩니다.

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

예제 데이터 세트 설치하기

설치가 완료되면 사용자 이름 elastic과 start-local 스크립트로 생성된 비밀번호(.env 파일에 저장됨)를 사용해 Kibana에 로그인할 수 있습니다.

Kibana에서 제공되는 eCommerce orders 데이터 세트를 설치할 수 있습니다. 이 데이터 세트에는 kibana_sample_data_ecommerce라는 단일 인덱스가 포함되어 있으며 전자상거래 웹사이트의 4,675개 주문 정보를 담고 있습니다. 각 주문에는 다음과 같은 정보가 포함되어 있습니다.

• 고객 정보(이름, ID, 생년월일, 이메일 등)
• 주문 날짜
• 주문 ID
• 제품(가격, 수량, ID, 카테고리, 할인 등을 포함한 전체 제품 목록)
• SKU
• 총액(세전, 세후)
• 총 수량
• 지리 정보(도시, 국가, 대륙, 위치, 지역)

샘플 데이터를 설치하려면 Kibana의 통합 페이지를 열고(상단 검색창에서 "통합"을 검색) "Sample Data"를 설치하세요. 자세한 내용은 다음 문서에서 확인할 수 있습니다: https://www.elastic.co/docs/explore-analyze/#gs-get-data-into-kibana

이 글의 목표는 Google MCP Toolbox를 설정해 Elasticsearch에 연결하고 자연어로 kibana_sample_data_ecommerce 인덱스와 손쉽게 상호작용하는 방법을 보여주는 것입니다.

Google MCP Toolbox

Google MCP Toolbox는 애플리케이션과 AI 에이전트가 데이터베이스와 안전하고 효율적으로 상호작용할 수 있도록 설계된 오픈 소스 MCP 서버입니다. 이전에는 'GenAI Toolbox for Databases'로 알려졌으나 Model Context Protocol(MCP)을 전면 지원하게 되면서 현재의 이름으로 변경되었습니다. 이 프로젝트의 목적은 연결 풀링, 인증, 통합 가시성 등과 같은 다양한 운영 관리 요소들을 백그라운드에서 처리하여 에이전트를 데이터베이스에 연결할 때 기존에 필요하던 번거로운 작업을 줄이는 데 있습니다.

Toolbox의 핵심은 개발자가 데이터베이스 상호작용을 캡슐화한 재사용 가능한 고수준 도구를 정의할 수 있도록 한다는 점입니다. 이러한 도구는 MCP 호환 클라이언트(예: AI 에이전트)에서 호출할 수 있으며 클라이언트가 저수준 SQL 쿼리를 구현하거나 데이터베이스 연결을 직접 관리할 필요가 없습니다. 이러한 접근 방식은 데이터베이스 인식 에이전트를 구축하는 데 필요한 보일러플레이트 코드(boilerplate code)의 양을 크게 줄여 단 몇 줄의 애플리케이션 로직만으로도 고급 데이터 처리 기능을 통합할 수 있게 합니다. 한 번 정의된 도구는 여러 에이전트, 프레임워크, 언어 간에 손쉽게 공유할 수도 있습니다(그림 1).

Toolbox를 사용할 때의 큰 장점 중 하나는 기본으로 제공되는 보안 모델입니다. OAuth2와 OIDC 같은 인증 흐름을 기본적으로 지원하므로 개발자는 에이전트에서 민감한 데이터베이스 자격 증명을 직접 다루거나 저장하지 않아도 됩니다. 또한 이 플랫폼은 OpenTelemetry를 통해 메트릭과 트레이싱을 포함한 통합 가시성 기능을 제공하며 이는 디버깅, 모니터링 및 프로덕션 배포에 필수적입니다. 종합하면 MCP Toolbox는 MCP를 지원하는 모든 시스템에서 데이터와 상호작용하기 위한 통합되고 안전하며 확장 가능한 인터페이스 역할을 합니다.

MCP Toolbox 설치 방법

다음 명령어를 사용하여 Linux에서 MCP Toolbox 서버를 설치할 수 있습니다.

export VERSION=0.21.0
curl -L -o toolbox https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

macOS 또는 Windows에 설치하려면 여기에 있는 자세한 안내를 따르세요.

Toolbox를 Elasticsearch용으로 구성하기

Elasticsearch용 MCP Toolbox를 구성하려면 다음과 같이 tools.yaml 파일을 생성해야 합니다.

sources:
  my-cluster:
    kind: elasticsearch
    addresses:
      - http://localhost:9200
    apikey: 

tools:
  customer-orders:
    kind: elasticsearch-esql
    source: my-cluster
    description: Get the orders made by a customer identified by name.
    query: |
    	FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name, {"operator": "AND"})
    parameters:
      - name: name
        type: string
        description: The customer name.

toolsets:
  elasticsearch-tools:
    - customer-orders

<insert-here-api-key> 값을 유효한 Elasticsearch API 키로 교체해야 합니다. 로컬에서 start-local로 Elasticsearch를 실행하고 있는 경우 생성된 .env 파일의 ES_LOCAL_API_KEY 변수에서 API 키를 확인할 수 있습니다. Elastic Cloud를 사용하는 경우 여기에 설명된 절차를 따라 API 키를 생성할 수 있습니다.

이전 도구에는 Elasticsearch를 위한 다음 ES|QL 쿼리가 포함되어 있습니다:

FROM kibana_sample_data_ecommerce | WHERE MATCH(customer_full_name, ?name)

ES|QL에 익숙하지 않다면 간단히 이렇게 이해할 수 있습니다. ES|QL은 Elastic이 개발한 쿼리 언어로 SQL과 비슷한 방식으로 하나 이상의 인덱스를 대상으로 데이터를 검색할 수 있습니다. ES|QL에 대한 더 자세한 내용은 여기에서 공식 문서를 통해 확인할 수 있습니다.

위의 쿼리는 ?name 매개변수(물음표는 매개변수를 의미)를 사용해 지정된 고객 이름이 포함된 모든 주문을 kibana_sample_data_ecommerce 인덱스에서 검색합니다.

고객 이름은 앞서 작성한 YAML 구성에서 string 타입과 'The customer name' 설명으로 정의되었습니다.

이 도구를 사용하면 고객인 Foo는 2025년 10월에 몇 건의 주문을 했나요?와 같은 고객의 주문 관련 질문에 답할 수 있습니다.

도구와 그 매개변수에 대한 설명은 사용자의 자연어 요청에서 관련 정보를 추출하는 데 매우 중요합니다. 이러한 정보 추출은 대규모 언어 모델(LLM)의 함수 호출 기능을 통해 수행됩니다. 실제로 LLM은 필요한 정보를 얻기 위해 실행해야 할 함수(도구)와 해당 함수에 필요한 매개변수를 자동으로 식별할 수 있습니다.

함수 호출에 대한 자세한 내용은 Ashish Tiwari가 작성한 OpenAI function calling with Elasticsearch(Elasticsearch와 함께 사용하는 OpenAI 함수 호출)라는 글을 참고하세요.

Toolbox 서버 실행하기

앞서 작성한 tools.yaml 파일을 사용해 MCP Toolbox를 다음 명령어로 실행할 수 있습니다.

./toolbox --tools-file tools.yaml --ui

-ui 매개변수를 사용하면 http://127.0.0.1:5000/ui에서 웹 애플리케이션이 실행됩니다(그림 2).

Tools > customer-orders를 선택한 뒤 name 매개변수에 고객 이름(예: Gwen Sanders)을 입력하고 Run Tool 버튼을 클릭할 수 있습니다. 그림 3에 표시된 것과 같은 JSON 응답이 표시됩니다.

이로써 설정이 완료되며 MCP Toolbox는 customer-orders 도구를 실행해 Elasticsearch와 통신하고 ES|QL 쿼리를 실행할 수 있습니다.

Gemini CLI와 함께 MCP Toolbox 사용하기

데이터베이스용 MCP Toolbox와의 통신에는 어떤 MCP 클라이언트든 사용할 수 있습니다. 예를 들어 Gemini를 사용하기 위한 명령줄 도구인 Gemini CLI를 사용할 수 있습니다. Gemini CLI는 여기에 안내된 지침에 따라 설치할 수 있습니다.

Gemini CLI에는 MCP Toolbox용으로 사전 구성된 확장 프로그램이 제공되며 gemini-cli-extensions/mcp-toolbox에서 사용할 수 있습니다. 다음 명령어를 실행해 이 확장 프로그램을 설치할 수 있습니다.

gemini extensions install https://github.com/gemini-cli-extensions/mcp-toolbox

설치가 완료되면 MCP Toolbox용 tools.yaml 설정 파일을 저장한 디렉터리로 이동한 뒤 다음과 같이 Gemini CLI를 실행해야 합니다. 이는 Gemini CLI가 MCP Toolbox와 자동으로 구성되기 위해 필요한 단계입니다.

gemini

그림 4에 표시된 출력 결과를 확인할 수 있습니다.

다음 명령어로 MCP Toolbox가 연결되어 있는지 확인할 수 있습니다.

/mcp list

mcp_toolbox 항목 아래에 customer-orders 도구가 나열된 것을 확인할 수 있습니다(그림 5).

MCP Toolbox가 Gemini CLI에 연결되었다면 이제 ”고객인 Gwen Sanders의 주문 내역을 알려주세요”와 같은 질문을 해볼 수 있습니다. 그러면 Gemini CLI가 mcp_toolbox 서버에서 customer-orders 도구를 실행할 수 있는 권한을 요청합니다(그림 6 참조).

확인되면 Gemini CLI는 MCP Toolbox에 요청을 보내 JSON 응답을 받은 다음 이를 바탕으로 최종 응답을 구성합니다(그림 7).

Gemini CLI의 응답에는 Gwen Sanders가 2개 상품을 한 번만 주문했으며 총액은 132유로라는 내용이 표시됩니다.

MCP Toolbox SDKs

Google MCP Toolbox는 Go, Python, JavaScript로 작성된 프로그램에서 모든 기능에 접근할 수 있는 SDK도 제공합니다.

예를 들어 Python SDK는 다음의 GitHub 페이지에서 이용할 수 있습니다: https://github.com/googleapis/mcp-toolbox-sdk-python

MCP Toolbox에 연결하기 위해 간단한 에이전트를 만들어야 합니다. 이를 위해 다음 패키지를 설치해야 합니다.

pip install toolbox-core
pip install google-adk

그리고 아래 명령어로 새로운 에이전트 프로젝트를 생성합니다.

adk create my_agent

이 명령을 실행하면 agent.py 파일이 포함된 my_agent라는 새 디렉터리가 생성됩니다.

Toolbox에 연결하기 위해 my_agent/agent.py를 다음 내용으로 업데이트합니다.

from google.adk import Agent
from google.adk.apps import App
from toolbox_core import ToolboxSyncClient

client = ToolboxSyncClient("http://127.0.0.1:5000")

root_agent = Agent(
    name='root_agent',
    model='gemini-2.5-flash',
    instruction="You are a helpful AI assistant designed to search information about a dataset of ecommerce orders.",
    tools=client.load_toolset(),
)

app = App(root_agent=root_agent, name="my_agent")

Google API 키를 포함한 .env 파일을 생성합니다.

echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > my_agent/.env

마지막으로 에이전트를 실행하여 결과를 확인할 수 있습니다. 에이전트를 실행하려면 아래 명령어를 입력합니다.

adk run my_agent

또는 웹 인터페이스로 제공할 수도 있습니다.

adk web --port 8000

두 경우 모두 Q&A 인터페이스를 통해 MCP Toolbox와 상호작용할 수 있습니다. 예를 들어 이전 예시처럼 고객인 Gwen Sanders의 주문 내역을 보여주세요라고 질문할 수 있습니다.

다양한 SDK에 대한 자세한 내용은 이 문서 페이지를 참고하세요.

결론

이번 글에서는 Google MCP Toolbox for Databases와 Elasticsearch를 통합하는 방법을 시연했습니다. 간단한 YAML 구성 파일만으로 ES|QL 언어를 활용해 자연어 질문을 Elasticsearch 쿼리로 변환하는 도구 세트를 정의할 수 있습니다.

또한 전자상거래 웹사이트의 주문 데이터를 포함하고 있는 kibana_sample_data_ecommerce 데이터 세트와 상호작용하는 방법을 시연했습니다. 이 설정 파일을 사용하면 MCP Toolbox 서버를 간단히 실행하고 모든 MCP 클라이언트에서 해당 서버에 연결할 수 있습니다.

마지막으로 Gemini CLI를 클라이언트로 사용해 MCP Toolbox for Databases에 연결하고 Elasticsearch에 저장된 전자상거래 데이터를 조회하는 과정을 시연했습니다. 특정 고객 이름을 기준으로 주문 정보를 조회하는 자연어 쿼리도 직접 실행해 보았습니다.

MCP 생태계가 계속 성장함에 따라 안전하고 프로덕션 환경에 바로 투입할 수 있는 인프라를 기반으로 한 경량 도구 정의 방식은 적은 노력으로도 점점 더 고도화되고 데이터에 정통한 에이전트를 구축할 수 있는 새로운 기회를 열어 줍니다. 로컬 환경에서 Elastic의 샘플 데이터 세트로 실험하는 경우나 대규모 애플리케이션에 검색 기능을 통합하는 경우에도 MCP Toolbox는 자연어를 통해 Elasticsearch 데이터와 상호작용할 수 있는 신뢰성 높고 확장 가능한 기반을 제공합니다.

에이전틱 AI 애플리케이션 개발에 대해 더 알고 싶다면 Anish Mathur와 Dana Juratoni가 작성한 Building AI Agentic Workflows with Elasticsearch(Elasticsearch로 AI 에이전틱 워크플로우 구축하기)라는 글을 참고해 보세요.

Google MCP Toolbox 관련 추가 정보는 https://googleapis.github.io/genai-toolbox/getting-started/introduction/에서 확인할 수 있습니다.

그러나 모든 케이스를 수동으로 테스트할 수 없기 때문에, 한 가지 문제를 해결하면 실수로 다른 쿼리가 손상될 수 있습니다. 하지만 특정 쿼리를 변경했을 때 다른 쿼리에 파급 효과를 미치는지 사용자 또는 QA 팀이 어떻게 테스트할 수 있을까요? 더 중요한 것은 변경 사항이 실제로 쿼리를 개선했는지 어떻게 확인할 수 있을까요?

체계적인 평가를 향해

이때 판단 목록이 유용하게 작용합니다. 변경할 때마다 수동 및 주관적 테스트에 의존하는 대신, 비즈니스 사례와 관련된 고정된 쿼리 세트와 해당 결과를 정의할 수 있습니다.

이 세트가 기준이 됩니다. 변경 사항을 구현할 때마다 검색이 실제로 개선되었는지 여부를 평가합니다.

이 접근 방식의 가치는 다음과 같습니다:

• 불확실성 제거: 변경 사항이 다른 쿼리에 영향을 미치는지를 데이터가 알려줍니다.
• 수동 테스트 중지: 판단 세트가 기록되면 테스트가 자동으로 진행됩니다.
• 변경 지원: 변경의 이점을 뒷받침하는 명확한 메트릭을 표시할 수 있습니다.

판단 목록을 만드는 방법

가장 쉽게 시작하는 방법 중 하나는 대표 검색어를 선택하고 관련 문서를 수동으로 고르는 것입니다. 이 목록을 작성할 때 두 가지 방법을 사용할 수 있습니다.

• 이진 판단: 쿼리와 연관된 각 문서에 관련 있음(보통 점수 1)과 관련 없음(0)이라는 간단한 태그가 붙습니다.
• 등급별 판단: 여기서는 문서마다 다른 수준의 점수가 매겨집니다. 예를 들어, Likert 척도와 유사하게 0~4 척도를 설정해 0은 '전혀 관련 없음', 4는 '매우 관련 있음'으로 정의하고, 그 사이에 '관련 있음', '어느 정도 관련 있음'과 같은 단계를 둘 수 있습니다.

이진 판단은 '이 문서가 결과에 포함되어야 하는가?'처럼 검색 의도에 명확한 한계가 있을 때 잘 작동합니다.

등급별 판단은 결과가 애매한 영역이 있을 때 더 유용합니다. 어떤 결과는 다른 결과보다 더 좋으므로 '매우 좋음', '좋음', '쓸모없음' 결과를 얻고, 결과의 순서와 사용자의 피드백을 중요시하는 메트릭을 사용할 수 있습니다. 그러나 등급 척도는 검토자마다 점수 수준을 다르게 사용해 판단의 일관성이 떨어질 수 있다는 단점도 갖고 있습니다. 또한 등급별 메트릭은 점수가 높으면 가중치를 더 많이 부여하기 때문에 작은 변화(예: 4점 대신 3점으로 평가)로도 검토자가 의도한 것보다 훨씬 더 큰 변화를 일으킬 수 있습니다. 이렇게 주관적인 요소가 추가되면 시간이 지남에 따라 등급별 판단이 더 복잡하고 관리하기 어려워집니다.

문서를 직접 분류해야 하나요?

반드시 그렇지는 않습니다. 판단 목록을 만드는 데는 여러 가지 방법이 있고 각각 고유한 장점과 단점이 있기 때문입니다.

• 명시적 판단: 여기서 중소기업은 각 쿼리/문서를 검토하고 관련성 여부(또는 방법)를 수동으로 결정합니다. 이는 품질과 제어 측면에서 장점을 제공하지만 확장성이 떨어집니다.
• 암묵적 판단: 이 방법은 클릭, 이탈률, 구매 등 실제 사용자 행동을 기반으로 관련 문서를 추론합니다. 이 방식을 사용하면 데이터를 자동으로 수집할 수 있지만 편향적일 수 있습니다. 예를 들어, 사용자들은 관련성이 없더라도 검색 결과 상단에 있는 항목을 더 자주 클릭하는 경향이 있습니다.
• AI 생성 판단: 이 마지막 옵션은 모델(예: LLM)을 사용하여 쿼리와 문서를 자동으로 평가하며, 흔히 LLM 배심원단이라고도 합니다. 빠르고 쉽게 확장할 수 있지만, 데이터의 품질은 사용 중인 모델의 품질과 LLM 학습 데이터가 비즈니스 관심사와 얼마나 잘 부합하는지에 달려 있습니다. 인간의 평가와 마찬가지로, LLM 배심원단 역시 편향이나 불일치를 도입할 수 있으므로 신뢰할 수 있는 소규모의 판단과 비교하여 결과를 검증하는 것이 중요합니다. LLM 모델은 본질적으로 확률적이기 때문에 온도 파라미터를 0으로 설정해도 같은 결과에 대해 서로 다른 등급을 부여하는 경우가 많습니다.

다음은 판단 세트를 만드는 가장 좋은 방법을 선택하기 위한 몇 가지 권장 사항입니다.

• 가격, 브랜드, 언어, 스타일, 제품 세부정보 등 사용자만 제대로 판단할 수 있는 일부 기능의 중요도를 결정합니다. 중요한 사항이라면 최소한 판단 목록의 일부에 대한 명시적인 판단이 필요합니다.
• 검색 엔진 트래픽이 이미 충분하여 클릭, 전환, 체류 시간 등의 지표를 활용해 사용 추세를 파악할 수 있는 경우, 암묵적 판단을 사용하세요. 하지만 편향(예: 사용자는 하위 순위의 결과가 더 관련성이 높더라도 상위 순위의 결과를 더 자주 클릭하는 경향이 있음)을 방지하기 위해 명시적인 판단 기준과 대조하여 신중하게 해석해야 합니다.

이를 해결하기 위해, 위치 편향 제거 기술이 클릭 데이터를 조정하거나 가중치를 조정하여 사용자의 진정한 관심을 더 잘 반영합니다. 몇 가지 접근 방식은 다음과 같습니다.

• 결과 순서 변경: 일부 사용자를 대상으로 검색 결과 순서를 변경하여 순위가 클릭에 미치는 영향을 추정합니다.
• 클릭 모델에는 동적 베이지안 네트워크 DBN, 사용자 브라우징 모델 UBM이 포함됩니다. 이러한 통계 모델은 스크롤, 체류 시간, 클릭 순서 및 결과 페이지로 돌아가는 등의 패턴을 사용하여 클릭이 단순한 위치가 아니라 실제 관심을 반영할 확률을 추정합니다.

예시: 영화 평점 앱

필수 구성 요소

이 예시를 실행하려면 Elasticsearch 8.x 클러스터가 로컬이나 Elastic Cloud Hosted(호스팅 또는 서버리스)를 실행하고, REST API 또는 Kibana에 접근할 수 있어야 합니다.

사용자가 영화에 대한 의견을 업로드하고 볼 영화를 검색할 수 있는 앱을 생각해 보세요. 사용자들이 직접 작성한 글이기 때문에 오타가 있거나, 표현 방식이 다양할 수 있습니다. 따라서 검색 엔진은 이러한 다양성을 해석하고 사용자에게 유용한 결과를 제공할 수 있어야 합니다.

전반적인 검색 동작에 영향을 주지 않고 쿼리를 반복적으로 수정할 수 있도록, 비즈니스 팀에서 가장 빈번하게 발생하는 검색어를 기반으로 다음과 같은 이진 판단 기준을 만들었습니다.

인덱스 생성:

PUT movies
{
  "mappings": {
    "properties": {
      "text": {
        "type": "text"
      }
    }
  }
}

대량 요청:

POST /movies/_bulk
{ "index": { "_id": "doc1" } }
{ "text": "DiCaprio performance in The Revenant was breathtaking." }
{ "index": { "_id": "doc2" } }
{ "text": "Inception shows Leonardo DiCaprio in one of his most iconic roles." }
{ "index": { "_id": "doc3" } }
{ "text": "Brad Pitt delivers a solid performance in this crime thriller." }
{ "index": { "_id": "doc4" } }
{ "text": "An action-packed adventure with stunning visual effects." }
{ "index": { "_id": "doc5" } }
{ "text": "A heartbreaking story of love and loss that made me cry for hours." }
{ "index": { "_id": "doc6" } }
{ "text": "One of the saddest movies ever made -- bring tissues!" }
{ "index": { "_id": "doc7" } }
{ "text": "A lighthearted comedy that will make you laugh." }
{ "index": { "_id": "doc8" } }
{ "text": "A science-fiction epic full of action and excitement." }

아래는 앱이 사용하는 Elasticsearch 쿼리입니다.

GET movies/_search
{
 "query": {
   "match": {
     "text": {
       "query": "DiCaprio performance",
       "minimum_should_match": "100%"
     }
   }
 }
}

판단에서 지표로

판단 목록은 그 자체로 많은 정보를 제공하지 않으며, 단지 쿼리 결과를 예상할 수 있을 뿐입니다. 그러나 검색 성능을 측정하기 위해 객관적인 메트릭을 계산할 때가 되면 판단 목록이 그 진가를 발휘합니다.

요즘 가장 많이 사용되는 메트릭은 다음과 같습니다.

• 정확도: 전체 검색 결과 중 실제 관련성이 있는 결과의 비율을 측정합니다.
• 리콜: 검색 엔진이 찾은 x개의 결과 중에서 관련성 있는 결과의 비율을 측정합니다.
• 할인 누적 이득(DCG): 결과 순위의 품질을 측정하며, 가장 관련성이 높은 결과가 최상위에 있어야 한다고 판단합니다.
• 평균 상호 순위(MRR): 첫 번째 관련 결과의 위치를 측정합니다. 목록에서 높은 위치에 있을수록 점수가 높아집니다.

동일한 영화 평점 앱을 예로 들어 리콜 메트릭을 계산하여 쿼리에서 누락된 정보가 있는지 확인해 보겠습니다.

Elasticsearch에서는 판단 목록을 사용하여 순위 평가 API를 통해 메트릭을 계산할 수 있습니다. 이 API는 판단 목록, 쿼리, 평가하려는 메트릭을 입력으로 받아 쿼리 결과와 판단 목록을 비교한 값을 반환합니다.

두 개의 쿼리에 대한 판단 목록을 실행해 보겠습니다.

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry",
             "minimum_should_match": "100%"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

'디카프리오' 쿼리와 '슬픈 영화' 쿼리, 두 가지 요청을 _rank_eval에 사용하겠습니다. 각 요청에는 쿼리와 해당 판단 목록(평가)이 포함됩니다. 평가에 포함되지 않은 문서는 판단이 없는 것으로 간주되므로 모든 문서에 등급을 매길 필요는 없습니다. 계산을 수행할 때 리콜은 평가에서 관련성이 있는 것으로 간주되는 문서인 '관련 세트'만 고려합니다.

이 경우, '디카프리오' 쿼리의 리콜은 1이고 '슬픈 영화'는 0입니다. 즉, 첫 번째 쿼리에서는 모든 관련 결과를 얻을 수 있었지만 두 번째 쿼리에서는 아무런 결과도 얻지 못했습니다. 따라서 평균 리콜은 0.5입니다.

{
 "metric_score": 0.5,
 "details": {
   "dicaprio-performance": {
     "metric_score": 1,
     "unrated_docs": [],
     "hits": [
       {
         "hit": {
           "_index": "movies",
           "_id": "doc1",
           "_score": 2.4826927
         },
         "rating": 1
       },
       {
         "hit": {
           "_index": "movies",
           "_id": "doc2",
           "_score": 2.0780432
         },
         "rating": 1
       }
     ],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 2,
         "relevant_docs": 2
       }
     }
   },
   "sad-movies": {
     "metric_score": 0,
     "unrated_docs": [],
     "hits": [],
     "metric_details": {
       "recall": {
         "relevant_docs_retrieved": 0,
         "relevant_docs": 2
       }
     }
   }
 },
 "failures": {}
}

쿼리의 모든 단어가 문서에 100% 포함되어야 한다고 요구하면 minimum_should_match 매개변수를 너무 엄격하게 적용해 관련성 있는 결과를 놓치고 있는 것일지도 모릅니다. 쿼리에서 단어가 하나만 발견되면 문서가 관련성이 있는 것으로 간주되도록 minimum_should_match 매개변수를 제거해 보겠습니다.

POST /movies/_rank_eval
{
 "requests": [
   {
     "id": "dicaprio-performance",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "DiCaprio performance"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc1",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc2",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc3",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc4",
         "rating": 0
       }
     ]
   },
   {
     "id": "sad-movies",
     "request": {
       "query": {
         "match": {
           "text": {
             "query": "sad movies that make you cry"
           }
         }
       }
     },
     "ratings": [
       {
         "_index": "movies",
         "_id": "doc5",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc6",
         "rating": 1
       },
       {
         "_index": "movies",
         "_id": "doc7",
         "rating": 0
       },
       {
         "_index": "movies",
         "_id": "doc8",
         "rating": 0
       }
     ]
   }
 ],
 "metric": {
   "recall": {
     "k": 10,
     "relevant_rating_threshold": 1
     }
 }
}

보시다시피, 두 쿼리 중 하나에서 minimum_should_match 매개 변수를 제거하면 두 쿼리 모두에서 평균 호출 횟수가 1이 됩니다.

{
  "metric_score": 1,
  "details": {
    "dicaprio-performance": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc1",
            "_score": 2.0661702
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc3",
            "_score": 0.732218
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc2",
            "_score": 0.6271719
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    },
    "sad-movies": {
      "metric_score": 1,
      "unrated_docs": [],
      "hits": [
        {
          "hit": {
            "_index": "movies",
            "_id": "doc7",
            "_score": 2.1307156
          },
          "rating": 0
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc5",
            "_score": 1.3160692
          },
          "rating": 1
        },
        {
          "hit": {
            "_index": "movies",
            "_id": "doc6",
            "_score": 1.190063
          },
          "rating": 1
        }
      ],
      "metric_details": {
        "recall": {
          "relevant_docs_retrieved": 2,
          "relevant_docs": 2
        }
      }
    }
  },
  "failures": {}
}

요약하면, minimum_should_match: 100% 절을 제거하면 두 쿼리 모두에 대해 완벽한 리콜을 얻을 수 있습니다.

됐습니다! 성공하셨죠?

그렇게 어렵지 않아요!

리콜을 개선함으로써 더 폭넓은 결과를 확보할 수 있게 됩니다. 그러나 각 조정에는 상충되는 부분이 있습니다. 따라서 다양한 메트릭을 사용해 변경 사항을 평가하는 완전한 테스트 케이스를 정의해야 합니다.

판단 목록과 메트릭을 사용하면 변경 사항을 적용할 때 근거 데이터가 생기므로, 감에 의존해 판단하는 일을 피할 수 있습니다. 검증은 더 이상 수동적이고 반복적이지 않으며, 한 가지 사용 사례뿐만 아니라 여러 사용 사례에서 변경 사항을 테스트할 수 있습니다. 번역:또한 A/B 테스트를 통해 어떤 설정이 사용자와 비즈니스 사례에 가장 적합한지 실제 환경에서 검증할 수 있어, 기술적 메트릭에서 출발해 실제 메트릭으로 다시 연결되는 선순환을 완성할 수 있습니다.

판단 목록 사용에 대한 최종 권장 사항

판단 목록을 활용하는 것은 단순히 측정하는 것뿐만 아니라, 자신 있게 반복할 수 있는 프레임워크를 만드는 것이기도 합니다. 이를 위해 다음 권장 사항을 따르세요:

1. 작은 시작이라도, 시작하세요. 각각 50개의 판단 목록이 있는 10,000개의 쿼리가 필요하지 않습니다. 비즈니스에 가장 중요한 쿼리를 5~10개 식별하고 결과의 상단에 표시할 문서를 정의하기만 하면 됩니다. 이것으로 이미 기반이 갖춰집니다. 일반적으로 상위 쿼리와 결과가 없는 쿼리부터 시작하는 것이 좋습니다. Precision과 같이 쉽게 구성할 수 있는 메트릭으로 테스트를 시작한 후, 복잡성을 높여 나갈 수 있습니다.
2. 사용자 검증을 통해 타당성을 검증하세요. 프로덕션 환경에서 A/B 테스트를 통해 수치를 보완하세요. 이렇게 하면 메트릭에서 좋아 보이던 변경 사항이 실제 영향을 발휘하고 있는지 알 수 있습니다.
3. 목록을 계속 유지하세요. 비즈니스 사례는 진화할 것이며 중요한 쿼리도 진화할 것입니다. 정기적으로 판단을 업데이트하여 새로운 필요를 반영하세요.
4. 워크플로의 일부로 만드세요. 판단 목록을 개발 파이프라인에 통합하세요. 각 구성 변경, 동의어 또는 텍스트 분석이 기본 목록에 대해 자동으로 검증되는지 확인하세요.
5. 기술 지식을 전략과 연결하세요. 정확도나 리콜과 같은 기술적 메트릭을 측정하는 데서 멈추지 마세요. 평가 결과를 활용하여 비즈니스 성과에 전달하세요.

LangGraph란?

LangGraph는 AI 에이전트를 구축하고 워크플로우에서 이를 오케스트레이션하여 AI 지원 애플리케이션을 생성하는 프레임워크입니다. LangGraph에는 작업을 나타내는 함수를 선언하고 워크플로우의 노드로 할당할 수 있는 노드 아키텍처가 있습니다. 여러 노드가 상호작용을 한 결과는 그래프가 됩니다. LangGraph는 모듈형 및 조합 가능한 AI 시스템을 구축하기 위한 도구를 제공하는 광범위한 LangChain 에코시스템의 일부입니다.

LangGraph가 유용한 이유를 더 잘 이해하기 위해 LangGraph를 사용하여 문제 상황을 해결해 보겠습니다.

솔루션 개요

벤처 캐피털 회사에서는 투자자들이 다양한 필터링 옵션을 갖춘 방대한 데이터베이스를 활용할 수 있지만, 기준을 결합하려고 하면 어렵고 시간이 오래 걸립니다. 이로 인해 일부 관련 스타트업이 투자 대상에서 제외될 수 있습니다. 결국 최적의 후보자를 찾는 데 많은 시간을 허비하거나, 심지어 기회를 놓치게 됩니다.

LangGraph와 Elasticsearch를 사용하면 자연어로 Elasticsearch 검색을 수행할 수 있어 사용자가 수십 개의 필터로 복잡한 요청을 수동으로 작성할 필요가 없습니다. 유연성을 높이기 위해 워크플로우는 사용자 입력에 따라 두 가지 쿼리 유형 중 하나를 자동으로 선택합니다.

• 투자 중심 쿼리: 펀딩 라운드, 가치 평가 또는 수익과 같은 스타트업의 금융 및 자금 조달 측면을 대상으로 합니다. 예시: "800만~2500만 달러의 시리즈 A 또는 시리즈 B 펀딩을 받고 월 매출이 50만 달러 이상인 스타트업을 찾아주세요."
• 시장 중심 쿼리: 이는 산업 분야, 지리적 시장 또는 비즈니스 모델에 집중하여 특정 부문이나 지역의 기회를 식별하는 데 도움을 줍니다. 예시: "샌프란시스코, 뉴욕 또는 보스턴에서 핀테크 및 헬스케어 스타트업을 찾으주세요."

쿼리를 견고하게 유지하기 위해 LLM이 검색 템플릿을 작성하도록 하고, 전체 DSL 쿼리 대신 사용합니다. 이렇게 하면 항상 원하는 쿼리를 얻을 수 있으며, LLM은 매번 필요한 쿼리를 작성할 필요 없이 빈칸만 채우면 됩니다.

시작에 필요한 사항

• Elasticsearch APIKey
• OpenAPI APIKey
• Node 18 이상 버전

단계별 지침

이 섹션에서는 앱이 어떻게 보일지 살펴보겠습니다. 이를 위해 TypeScript를 사용하겠습니다. TypeScript는 JavaScript의 상위 집합으로, 정적 타입을 추가하여 코드의 안정성, 유지관리 용이성, 안전성을 높이고 기존 JavaScript와의 완벽한 호환성을 유지하면서도 오류를 조기에 발견할 수 있도록 합니다.

노드의 흐름은 다음과 같습니다.

위 이미지는 LangGraph에서 생성되었으며, 노드 간의 실행 순서와 조건부 로직을 정의하는 워크플로우를 나타냅니다.

• decideStrategy: LLM을 사용하여 사용자의 쿼리를 분석하고 두 가지 전문 검색 전략, 즉 투자 중심 또는 시장 중심 중 하나를 결정합니다.
• prepareInvestmentSearch: 쿼리에서 필터 값을 추출하고 금융 및 자금 조달 관련 매개변수를 강조하는 사전 정의된 템플릿을 작성합니다.
• prepareMarketSearch: 필터 값을 추출할 뿐만 아니라 시장, 산업 및 지리적 컨텍스트를 강조하는 매개변수를 동적으로 구축합니다.
• executeSearch: 구성된 쿼리를 검색 템플릿을 사용하여 Elasticsearch로 전송하고 일치하는 스타트업 문서를 검색합니다.
• visualizeResults: 최종 결과를 자금 조달, 산업, 수익과 같은 주요 스타트업 속성을 보여주는 명확하고 읽기 쉬운 요약 형식으로 구성합니다.

이 흐름에는 사용자의 입력에 따라 투자 또는 시장 검색 경로를 선택하는 'if' 문 역할을 하는 조건부 분기가 포함되어 있습니다. LLM에 의해 구동되는 이러한 결정 로직은 워크플로우를 적응적이고 컨텍스트에 맞게 만들어줍니다. 다음 섹션에서 이 메커니즘에 대해 더 자세히 살펴보겠습니다.

LangGraph 상태

각 노드를 개별적으로 보기 전에 노드가 어떻게 통신하고 데이터를 공유하는지 이해해야 합니다. 이를 위해 LangGraph를 사용하여 워크플로우 상태를 정의할 수 있습니다. 이는 노드 간에 전달될 공유 상태를 정의합니다.

상태는 워크플로우 전반에 걸쳐 중간 데이터를 저장하는 공유 컨테이너 역할을 합니다. 사용자의 자연어 쿼리로 시작하여 선택한 검색 전략, Elasticsearch에 준비된 매개변수, 검색 결과, 마지막으로 형식화된 출력을 유지합니다.

이 구조는 모든 노드가 상태를 읽고 업데이트할 수 있도록 하여 사용자 입력에서 최종 시각화까지 정보의 일관된 흐름을 보장합니다.

const VCState = Annotation.Root({
  input: Annotation(), // User's natural language query
  searchStrategy: Annotation(), // Search strategy chosen by LLM
  searchParams: Annotation(), // Prepared search parameters
  results: Annotation(), // Search results
  final: Annotation(), // Final formatted response
});

애플리케이션 설정

이 섹션의 모든 코드는 elasticsearch-labs 리포지토리에서 확인할 수 있습니다.

앱이 위치할 폴더에서 터미널을 열고 다음 명령어로 Node.js 애플리케이션을 초기화합니다.

npm init -y

이제 이 프로젝트에 필요한 필수 종속성을 설치할 수 있습니다.

npm install @elastic/elasticsearch @langchain/langgraph @langchain/openai @langchain/core dotenv zod && npm install --save-dev @types/node tsx typescript

• @elastic/elasticsearch: 데이터 수집 및 검색과 같은 Elasticsearch 요청을 처리하는 데 도움이 됩니다.
• @langchain/langgraph: 모든 LangGraph 도구를 제공하기 위한 JS 종속성입니다.
• @langchain/openai: LangChain을 위한 OpenAI LLM 클라이언트.
• @langchain/core: 프롬프트 템플릿 등 LangChain 앱을 위한 기본 구성 요소를 제공합니다.
• dotenv: JavaScript에서 환경 변수를 사용하기 위한 필수 종속성입니다.
• zod: 유형 데이터에 대한 종속성입니다.

@types/node tsx typescript TypeScript 코드를 작성하고 실행할 수 있게 해줍니다.

이제 다음 파일을 생성합니다.

• elasticsearchSetup.ts: 인덱스 매핑을 생성하고 JSON 파일에서 데이터 세트를 로드한 후 Elasticsearch에 데이터를 수집합니다.
• main.ts: LangGraph 애플리케이션을 포함합니다.
• .env: 환경 변수를 저장하기 위한 파일

.env 파일에 다음 환경 변수를 추가합시다:

ELASTICSEARCH_ENDPOINT="your-endpoint-here"
ELASTICSEARCH_API_KEY="your-key-here"
OPENAI_API_KEY="your-key-here"

OpenAPI APIKey는 코드에서 직접 사용되지 않으며, 대신 라이브러리 @langchain/openai에서 내부적으로 사용됩니다.

모든 매핑 생성, 검색 템플릿 생성 및 데이터 세트 수집과 관련된 로직은 elasticsearchSetup.ts 파일에서 확인할 수 있습니다. 다음 단계에서는 main.ts 파일에 초점을 맞추겠습니다. 또한 데이터 세트를 확인하여 dataset.json 에서 데이터가 어떻게 보이는지 더 잘 이해할 수 있습니다.

LangGraph 앱

main.ts 파일에서 LangGraph 애플리케이션을 통합하기 위해 필요한 몇 가지 종속성을 가져오겠습니다. 이 파일에는 노드 함수와 상태 선언도 포함해야 합니다. 그래프 선언은 다음 단계에서 main 메서드로 진행됩니다. elasticsearchSetup.ts 파일에는 향후 단계에서 노드 내에서 사용할 Elasticsearch 도우미가 포함됩니다.

import { writeFileSync } from "node:fs";
import { StateGraph, Annotation, START, END } from "@langchain/langgraph";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";
import {
  esClient,
  ingestDocuments,
  createSearchTemplates,
  INDEX_NAME,
  INVESTMENT_FOCUSED_TEMPLATE,
  MARKET_FOCUSED_TEMPLATE,
  createIndex,
} from "./elasticsearchSetup.js";

const llm = new ChatOpenAI({ model: "gpt-4o-mini" });

앞서 언급한 바와 같이 LLM 클라이언트는 사용자의 질문에 따라 Elasticsearch 검색 템플릿 매개변수를 생성하는 데 사용됩니다.

async function saveGraphImage(app: any): Promise {
  try {
    const drawableGraph = app.getGraph();
    const image = await drawableGraph.drawMermaidPng();
    const arrayBuffer = await image.arrayBuffer();

    const filePath = "./workflow_graph.png";
    writeFileSync(filePath, new Uint8Array(arrayBuffer));
    console.log(`📊 Workflow graph saved as: ${filePath}`);
  } catch (error: any) {
    console.log("⚠️  Could not save graph image:", error.message);
  }
}

해당 메서드는 그래프 이미지를 png 형식으로 생성하고 Mermaid.INK API를 백그라운드에서 사용합니다. 이는 앱 노드가 스타일이 지정된 시각화와 어떻게 상호작용을 하는지 확인하려는 경우에 유용합니다.

LangGraph 노드

이제 각 노드를 자세히 살펴보겠습니다.

decideSearchStrategy 노드

decideSearchStrategy 노드는 사용자 입력을 분석하여 투자 중심 검색을 수행할지 시장 중심 검색을 수행할지 결정합니다. 이 노드는 정형 출력 스키마(Zod로 정의됨)가 있는 LLM을 사용해 쿼리 유형을 분류합니다. 결정을 내리기 전에 집계를 사용하여 인덱스에서 사용 가능한 필터를 검색하여 모델이 산업, 위치 및 자금 조달 데이터에 대한 최신 컨텍스트를 갖출 수 있도록 합니다.

필터 가능한 값을 추출하여 LLM으로 전송하기 위해 집계 쿼리를 사용하여 Elasticsearch 인덱스에서 직접 검색해 보겠습니다. 이 로직은 getAvailableFilters 이라는 메서드에 할당되어 있습니다.

async function getAvailableFilters() {
  try {
    const response = await esClient.search({
      index: INDEX_NAME,
      size: 0,
      aggs: {
        industries: {
          terms: { field: "industry", size: 100 },
        },
        locations: {
          terms: { field: "location", size: 100 },
        },
        funding_stages: {
          terms: { field: "funding_stage", size: 20 },
        },
        business_models: {
          terms: { field: "business_model", size: 10 },
        },
        lead_investors: {
          terms: { field: "lead_investor", size: 100 },
        },
        funding_amount_stats: {
          stats: { field: "funding_amount" },
        },
      },
    });

    return response.aggregations;
  } catch (error) {
    console.error("❌ Error getting available filters:", error);
    return {};
  }
}

위의 집계 쿼리로 다음과 같은 결과를 얻었습니다.

{
  "industries": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "logistics",
        "doc_count": 5
      },
      ...
    ]
  },
  "locations": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "San Francisco, CA",
        "doc_count": 4
      },
      {
        "key": "New York, NY",
        "doc_count": 3
      },
      ...
    ]
  },
  "funding_stages": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Series A",
        "doc_count": 8
      },
      ...
    ]
  },
  "business_models": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "B2B",
        "doc_count": 13
      },
      ...
    ]
  },
  "lead_investors": {
    "doc_count_error_upper_bound": 0,
    "sum_other_doc_count": 0,
    "buckets": [
      {
        "key": "Battery Ventures",
        "doc_count": 1
      },
      {
        "key": "Benchmark Capital",
        "doc_count": 1
      },
      ...
    ]
  },
  "funding_amount_stats": {
    "count": 20,
    "min": 4500000,
    "max": 35000000,
    "avg": 14075000,
    "sum": 281500000
  }
}

여기에서 모든 결과를 확인하세요.

두 가지 전략 모두 하이브리드 검색을 사용하여 질문의 정형적인 부분(필터)과 보다 주관적인 부분(시맨틱)을 모두 탐지합니다. 다음은 검색 템플릿을 사용한 두 쿼리의 예입니다.

await esClient.putScript({
      id: INVESTMENT_FOCUSED_TEMPLATE,
      script: {
        lang: "mustache",
        source: `{
          "size": 5,
          "retriever": {
            "rrf": {
              "retrievers": [
                {
                  "standard": {
                    "query": {
                      "semantic": {
                        "field": "semantic_field",
                        "query": "{{query_text}}"
                      }
                    }
                  }
                },
                {
                  "standard": {
                    "query": {
                      "bool": {
                        "filter": [
                          {"terms": {"funding_stage": {{#join}}{{#toJson}}funding_stage{{/toJson}}{{/join}}}},
                          {"range": {"funding_amount": {"gte": {{funding_amount_gte}}{{#funding_amount_lte}},"lte": {{funding_amount_lte}}{{/funding_amount_lte}}}}},
                          {"terms": {"lead_investor": {{#join}}{{#toJson}}lead_investor{{/toJson}}{{/join}}}},
                          {"range": {"monthly_revenue": {"gte": {{monthly_revenue_gte}}{{#monthly_revenue_lte}},"lte": {{monthly_revenue_lte}}{{/monthly_revenue_lte}}}}}
                        ]
                      }
                    }
                  }
                }
              ],
              "rank_window_size": 100,
              "rank_constant": 20
            }
          }
        }`,
      },
    });

자세히 설명된 쿼리는 elasticsearchSetup.ts 파일에서 확인하세요. 다음 노드에서는 두 쿼리 중 어떤 쿼리를 사용할지 결정합니다.

// Node 1: Decide search strategy using LLM
async function decideSearchStrategy(state: typeof VCState.State) {
  // Zod schema for specialized search strategy decision
  const SearchDecisionSchema = z.object({
    search_type: z
      .enum(["investment_focused", "market_focused"])
      .describe("Type of specialized search strategy to use"),
    reasoning: z
      .string()
      .describe("Brief explanation of why this search strategy was chosen"),
  });

  const decisionLLM = llm.withStructuredOutput(SearchDecisionSchema);

  // Get dynamic filters from Elasticsearch
  const availableFilters = await getAvailableFilters();

  const prompt = `Query: "${state.input}"
    Available filters: ${JSON.stringify(availableFilters, null, 2)}

    Choose between two specialized search strategies:
    
    - investment_focused: For queries about funding stages, funding amounts, monthly revenue, lead investors, financial performance
    
    - market_focused: For queries about industries, locations, business models, market segments, geographic markets
    
    Analyze the query intent and choose the most appropriate strategy.
  `;

  try {
    const result = await decisionLLM.invoke(prompt);
    console.log(
      `🤔 Search strategy: ${result.search_type} - ${result.reasoning}`
    );

    return {
      searchStrategy: result.search_type,
    };
  } catch (error: any) {
    console.error("❌ Error in decideSearchStrategy:", error.message);
    return {
      searchStrategy: "investment_focused",
    };
  }
}

prepareInvestmentSearch 및 prepareMarketSearch 노드

두 노드 모두 extractFilterValues이라는 공유 도우미 함수를 사용하는데, 이 함수는 LLM을 활용하여 사용자 입력에 언급된 관련 필터(산업, 위치, 자금 조달 단계, 비즈니스 모델 등)를 식별합니다. 이 스키마를 사용하여 검색 템플릿을 작성하고 있습니다.

// Extract all possible filter values from user input
async function extractFilterValues(input: string) {
  const FilterValuesSchema = z.object({
    // Investment-focused filters
    funding_stage: z
      .array(z.string())
      .default([])
      .describe("Funding stage values mentioned in query"),
    funding_amount_gte: z
      .number()
      .default(0)
      .describe("Minimum funding amount in USD"),
    funding_amount_lte: z
      .number()
      .default(100000000)
      .describe("Maximum funding amount in USD"),
    lead_investor: z
      .array(z.string())
      .default([])
      .describe("Lead investor values mentioned in query"),
    monthly_revenue_gte: z
      .number()
      .default(0)
      .describe("Minimum monthly revenue in USD"),
    monthly_revenue_lte: z
      .number()
      .default(10000000)
      .describe("Maximum monthly revenue in USD"),
    industry: z
      .array(z.string())
      .default([])
      .describe("Industry values mentioned in query"),
    location: z
      .array(z.string())
      .default([])
      .describe("Location values mentioned in query"),
    business_model: z
      .array(z.string())
      .default([])
      .describe("Business model values mentioned in query"),
  });

  const extractorLLM = llm.withStructuredOutput(FilterValuesSchema);
  const availableFilters = await getAvailableFilters();

  const extractPrompt = `Extract ALL relevant filter values from: "${input}"
    Available options: ${JSON.stringify(availableFilters, null, 2)}
    Extract only values explicitly mentioned in the query. Leave fields empty if not mentioned.`;

  return await extractorLLM.invoke(extractPrompt);
}

탐지된 의도에 따라 워크플로우는 다음 두 가지 경로 중 하나를 선택합니다.

prepareInvestmentSearch: 자금 조달 단계, 자금 조달 금액, 투자자 및 갱신 정보 등 금융 지향적 검색 매개변수를 구축합니다. 전체 쿼리 템플릿은 elasticsearchSetup.ts 파일에서 확인할 수 있습니다.

// Node 2A: Prepare Investment-Focused Search Parameters 
async function prepareInvestmentSearch(state: typeof VCState.State) {
  console.log(
    "💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: INVESTMENT_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing investment-focused params:", error);
    return {
      searchParams: {},
    };
  }
}

prepareMarketSearch: 산업, 지역, 비즈니스 모델에 초점을 맞춘 시장 기반 매개변수를 생성합니다. 전체 쿼리는 elasticsearchSetup.ts 에서 확인하세요.

// Node 2B: Prepare Market-Focused Search Parameters
async function prepareMarketSearch(state: typeof VCState.State) {
  console.log(
    "🔍 Preparing MARKET-FOCUSED search parameters with market emphasis..."
  );

  try {
    // Extract all filter values from input
    const values = await extractFilterValues(state.input);

    let searchParams: any = {
      template_id: MARKET_FOCUSED_TEMPLATE,
      query_text: state.input,
      ...values,
    };

    return { searchParams };
  } catch (error) {
    console.error("❌ Error preparing market-focused params:", error);
    return {};
  }
}

executeSearch 노드

이 node는 상태에서 생성된 검색 매개변수를 가져와 먼저 _render API 를 사용하여 디버깅 목적으로 쿼리를 시각화한 후, 결과를 검색하기 위해 Elasticsearch로 요청을 보냅니다.

// Node 3: Execute Search
async function executeSearch(state: typeof VCState.State) {
  const { searchParams } = state;

  try {
    // getting formed query from template for debugging
    const renderedTemplate = await esClient.renderSearchTemplate({
      id: searchParams.template_id,
      params: searchParams,
    });

    console.log(
      "📋 Complete query:",
      JSON.stringify(renderedTemplate.template_output, null, 2)
    );

    const results = await esClient.searchTemplate({
      index: INDEX_NAME,
      id: searchParams.template_id,
      params: searchParams,
    });

    return {
      results: results.hits.hits.map((hit: any) => hit._source),
    };
  } catch (error: any) {
    console.error(`❌ ${state.searchParams.search_type} search error:`, error);
    return { results: [] };
  }
}

visualizeResults 노드

마지막으로, 이 node는 Elasticsearch 결과를 표시합니다.

// Node 4: Visualize results
async function visualizeResults(state: typeof VCState.State) {
  const results = state.results || [];

  let formattedResults = `🎯 Found ${results.length} startups matching your criteria:\n\n`;

  results.forEach((startup: any, index: number) => {
    formattedResults += `${index + 1}. **${startup.company_name}**\n`;
    formattedResults += `   📍 ${startup.location} | 🏢 ${startup.industry} | 💼 ${startup.business_model}\n`;
    formattedResults += `   💰 ${startup.funding_stage} - $${(
      startup.funding_amount / 1000000
    ).toFixed(1)}M\n`;
    formattedResults += `   👥 ${startup.employee_count} employees | 📈 $${(
      startup.monthly_revenue / 1000
    ).toFixed(0)}K MRR\n`;
    formattedResults += `   🏦 Lead: ${startup.lead_investor}\n`;
    formattedResults += `   📝 ${startup.description}\n\n`;
  });

  return {
    final: formattedResults,
  };
}

프로그래밍 방식으로 전체 그래프는 다음과 같습니다.

  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow

보시다시피 앱이 다음에 실행할 '경로' 또는 '노드'를 결정하는 조건부 엣지가 있습니다. 이 기능은 워크플로우에서 여러 도구 중 하나를 선택하거나 인간이 개입하는 단계를 포함하는 등 분기 로직이 필요할 때 유용합니다.

LangGraph의 핵심 기능을 이해하면 다음과 같이 코드가 실행될 애플리케이션을 설정할 수 있습니다.

main 메서드에 모든 것을 통합합니다. 여기서는 변수 워크플로우 아래의 모든 요소를 포함하는 그래프를 선언합니다.

async function main() {
  await createIndex();
  await createSearchTemplates();
  await ingestDocuments();

  // Create the workflow graph with shared state
  const workflow = new StateGraph(VCState)
    // Register nodes - these are the processing functions
    .addNode("decideStrategy", decideSearchStrategy)
    .addNode("prepareInvestment", prepareInvestmentSearch)
    .addNode("prepareMarket", prepareMarketSearch)
    .addNode("executeSearch", executeSearch)
    .addNode("visualizeResults", visualizeResults)
    // Define execution flow with conditional branching
    .addEdge(START, "decideStrategy") // Start with strategy decision
    .addConditionalEdges(
      "decideStrategy",
      (state: typeof VCState.State) => state.searchStrategy, // Conditional function
      {
        investment_focused: "prepareInvestment", // If investment focused -> RRF template preparation
        market_focused: "prepareMarket", // If market focused -> dynamic query preparation
      }
    )
    .addEdge("prepareInvestment", "executeSearch") // Investment prep -> execute
    .addEdge("prepareMarket", "executeSearch") // Market prep -> execute
    .addEdge("executeSearch", "visualizeResults") // Execute -> visualize
    .addEdge("visualizeResults", END); // End workflow


  const app = workflow.compile();

  await saveGraphImage(app);

  const query =
    "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K";

  const marketResult = await app.invoke({ input: query });
  console.log(marketResult.final);
}

쿼리 변수는 가상의 검색창에 입력된 사용자 입력을 시뮬레이션합니다.

"800만~2500만 달러의 시리즈 A 또는 시리즈 B 펀딩을 받고 월 매출이 50만 달러 이상인 스타트업을 찾아주세요"라는 자연어 문구에서 모든 필터가 추출됩니다.

마지막으로 다음과 같이 메인 메서드를 호출합니다.

main().catch(console.error);

결과

🔍 Checking if index exists...
🏗️ Creating index...
✅ Index created successfully!
Ingesting documents...
✅ Documents ingested successfully!
✅ Investment-focused template created successfully!
✅ Market-focused template created successfully!

📊 Workflow graph saved as: ./workflow_graph.png

🔍 Query: "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"

🤔 Search strategy: investment_focused - The query specifically seeks profitable fintech startups with defined funding amounts and high monthly revenue, which aligns closely with financial performance metrics and investment-related criteria.

💰 Preparing INVESTMENT-FOCUSED search parameters with financial emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find startups with Series A or Series B funding between $8M-$25M and monthly revenue above $500K"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "funding_stage": [
                        "Series A",
                        "Series B"
                      ]
                    }
                  },
                  {
                    "range": {
                      "funding_amount": {
                        "gte": 8000000,
                        "lte": 25000000
                      }
                    }
                  },
                  {
                    "terms": {
                      "lead_investor": []
                    }
                  },
                  {
                    "range": {
                      "monthly_revenue": {
                        "gte": 500000,
                        "lte": 0
                      }
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 100,
      "rank_constant": 20
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **TechFlow**
   📍 San Francisco, CA | 🏢 logistics | 💼 B2B
   💰 Series A - $8.0M
   👥 45 employees | 📈 $500K MRR
   🏦 Lead: Sequoia Capital
   📝 TechFlow optimizes supply chain operations using AI-powered route optimization and real-time tracking. Founded in 2023, shows remarkable growth with $500K monthly revenue.

2. **DataViz**
   📍 New York, NY | 🏢 enterprise software | 💼 B2B
   💰 Series A - $10.0M
   👥 42 employees | 📈 $450K MRR
   🏦 Lead: Battery Ventures
   📝 DataViz creates intuitive data visualization tools for enterprise customers. No-code platform allows business users to create dashboards without technical expertise.

3. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

4. **UrbanMobility**
   📍 New York, NY | 🏢 logistics | 💼 B2B2C
   💰 Series B - $15.0M
   👥 78 employees | 📈 $750K MRR
   🏦 Lead: Kleiner Perkins
   📝 UrbanMobility revolutionizes urban transportation through autonomous delivery drones and smart logistics hubs. Partners with major retailers for same-day delivery across Manhattan and Brooklyn.

5. **HealthTech Solutions**
   📍 Boston, MA | 🏢 healthcare | 💼 B2B
   💰 Series B - $18.0M
   👥 95 employees | 📈 $900K MRR
   🏦 Lead: General Catalyst
   📝 HealthTech Solutions develops medical devices and software for remote patient monitoring. Comprehensive telehealth platform reducing hospital readmissions by 30%.

✨  Done in 18.80s.

전송된 입력에 대해 애플리케이션은 투자 중심 경로를 선택합니다. 그 결과, LangGraph 워크플로우에서 생성된 Elasticsearch 쿼리를 확인할 수 있으며, 이 쿼리는 사용자 입력에서 값과 범위를 추출합니다. 추출된 값이 적용된 쿼리가 Elasticsearch로 전송된 것을 볼 수 있으며, 마지막으로 visualizeResults 노드에 의해 형식이 지정된 결과를 확인할 수 있습니다.

이제 “샌프란시스코, 뉴욕 또는 보스턴에서 핀테크 및 헬스케어 스타트업을 찾아주세요”라는 쿼리를 사용하여 시장 중심 노드를 테스트해 보겠습니다.

...

🔍 Query: Find fintech and healthcare startups in San Francisco, New York, or Boston

🤔 Search strategy: market_focused - The query is focused on finding fintech startups in San Francisco that are disrupting traditional banking and payment systems, which pertains to specific industries (fintech) and locations (San Francisco). Thus, a market-focused strategy is more appropriate.

🔍 Preparing MARKET-FOCUSED search parameters with market emphasis...

📋 Complete query: {
  "size": 5,
  "retriever": {
    "rrf": {
      "retrievers": [
        {
          "standard": {
            "query": {
              "semantic": {
                "field": "semantic_field",
                "query": "Find fintech and healthcare startups in San Francisco, New York, or Boston"
              }
            }
          }
        },
        {
          "standard": {
            "query": {
              "bool": {
                "filter": [
                  {
                    "terms": {
                      "industry": [
                        "fintech",
                        "healthcare"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "location": [
                        "San Francisco, CA",
                        "New York, NY",
                        "Boston, MA"
                      ]
                    }
                  },
                  {
                    "terms": {
                      "business_model": []
                    }
                  }
                ]
              }
            }
          }
        }
      ],
      "rank_window_size": 50,
      "rank_constant": 10
    }
  }
}
🎯 Found 5 startups matching your criteria:

1. **FinanceAI**
   📍 San Francisco, CA | 🏢 fintech | 💼 B2C
   💰 Series C - $25.0M
   👥 120 employees | 📈 $1200K MRR
   🏦 Lead: Tiger Global Management
   📝 FinanceAI provides AI-powered investment advisory services to retail investors. Uses machine learning to analyze market trends with over 100,000 active users.

2. **CryptoWallet**
   📍 Miami, FL | 🏢 fintech | 💼 B2C
   💰 Series B - $16.0M
   👥 73 employees | 📈 $820K MRR
   🏦 Lead: Coinbase Ventures
   📝 CryptoWallet provides secure digital wallet solutions for cryptocurrency trading and storage. Multi-chain support with enterprise-grade security features.

...

✨  Done in 7.41s.

학습

글을 쓰는 과정에서 배운 점은 다음과 같습니다.

• LLM에 필터의 정확한 값을 표시해야 합니다. 그렇지 않으면 사용자가 정확한 값을 입력해야 합니다. 카디널리티가 낮을 때는 이 방법이 괜찮지만, 카디널리티가 높을 때는 결과를 필터링할 메커니즘이 필요합니다.
• 검색 템플릿을 사용하면 LLM이 Elasticsearch 쿼리를 작성하게 하는 것보다 훨씬 더 일관되고 더 빠른 결과를 얻을 수 있습니다.
• 조건부 엣지는 여러 변형과 분기 경로를 갖춘 애플리케이션을 구축하는 강력한 메커니즘입니다.
• 정형 출력은 예측 가능하고 형식에 안전한 응답을 적용하므로 LLM으로 정보를 생성할 때 매우 유용합니다. 이렇게 하면 안정성이 향상되고 즉각적인 오해를 줄일 수 있습니다.

하이브리드 검색을 통해 시맨틱 및 정형 검색을 결합하면 정확도와 컨텍스트 이해의 균형을 유지하면서 더 정확하고 관련성 높은 결과를 얻을 수 있습니다.

결론

이 예시에서는 LangGraph.js를 Elasticsearch와 결합하여 자연어 쿼리를 해석하고 금융 또는 시장 중심의 검색 전략을 선택할 수 있는 동적 워크플로우를 만듭니다. 이러한 접근 방식은 수동 쿼리의 복잡성을 줄이고 벤처 캐피털 분석가의 유연성과 정확성을 향상합니다.

변수 제어란 무엇인가요?

이전에 Kibana 대시보드를 사용해 본 적이 있다면, 아마도 클래식 대시보드 제어를 알고 계실 것입니다. 데이터에서 값을 표시하여 몇 번의 클릭만으로 항목을 필터링할 수 있는 편리한 드롭다운입니다.

변수 제어는 겉보기에는 비슷해 보이지만, 독창적인 차별점이 있습니다. 대시보드의 모든 패널을 자동으로 필터링하는 대신, 개별 시각화 내의 ES|QL 쿼리에 직접 연결할 수 있습니다.

즉, 사용자가 각 제어가 적용되는 위치를 결정할 수 있습니다. 더욱 좋은 점은, 시간 간격 조정, 분석 필드 전환, 시각화 매개변수 실시간 변경 등 다양한 창의적인 트릭에 활용할 수 있다는 것입니다. 기본적으로, 대시보드는 진정한 상호 작용 경험을 제공하여 인사이트를 더 빠르고 쉽게 얻을 수 있습니다.

변수 제어 사용 사례

좋습니다, 변수 제어는 유용한 것 같은데요. 그렇다면 실제로 무엇을 할 수 있을까요? 대시보드 수준을 높이는 몇 가지 예는 다음과 같습니다.

선택한 시각화 필터링

일부 시각화는 필터링하고 다른 시각화는 그대로 두고 싶으신가요? 변수 제어를 사용하면 바로 그렇게 할 수 있습니다. 응답할 패널을 선택하고 시각화의 기반이 되는 ES|QL 쿼리에 연결하세요.

다른 시간 간격을 선택하세요

사용자에게 '5분', '1시간', '1일' 등 원하는 시간 버킷으로 전환할 수 있는 권한을 부여합니다. 미리 정의된 간격으로 변수 제어를 작성하고 시계열 쿼리에 연결합니다.

함수 변경

각 작업에 대해 여러 차트를 생성하는 대신, 대시보드 사용자가 최대값, 평균값, 다양한 백분위수 또는 다른 집계기를 선택할 수 있도록 합니다.

다양한 필드로 그룹화

조사 중에는 데이터를 다양한 차원으로 세분화해야 할 때가 있습니다. 변수 제어를 통해 여러 '그룹별' 필드를 정의하고, 대시보드 사용자들이 자신만의 인사이트를 발견하는 데 가장 적합한 필드를 선택할 수 있게 할 수 있습니다.

어떻게 만들 수 있나요?

변수 제어를 만드는 가장 쉽게 (그리고 아마도 가장 즐겁게 만드는) 방법은 시각화의 ES|QL 쿼리 편집기에서 직접 만드는 것입니다. 쿼리를 입력하기 시작하고 자동 완성 메뉴를 사용하면 Kibana가 제어 구성을 훌륭히 도와줍니다.

하지만 변수 자체에서 시작하고 싶다면 패널 추가 → 제어 → 변수 제어 로 이동하여 제어를 만든 후 시각화에 변수를 추가할 수도 있습니다.

예제 1: 다중 값 선택 기능을 갖춘 필터링 제어

1. ES|QL 쿼리로 구동되는 시각화를 선택하고 WHERE 절에서 '제어 생성'을 클릭합니다.

2. 자동으로 변수 생성 플라이아웃으로 리디렉션되며, '쿼리에서 값 가져오기' 유형이 선택되고 변수 이름이 이미 입력되어 있습니다. 시각화 쿼리에서 작동하려면 컨트롤의 이름이 항상 '?...'로 시작해야 합니다.

대시보드에서 선택된 시간 범위에 따라 필드의 값을 가져오고 업데이트하려면 보통 이런 쿼리가 필요합니다.

FROM 
| WHERE @timestamp <=?_tend and @timestamp >?_tstart
| STATS BY 

3. 제어를 저장하면 대시보드 상단에 제어가 나타나고, 시각화 쿼리가 변수 제어 이름으로 업데이트됩니다.

4. 제어에 다중 값 선택을 추가하려면 쿼리에서 MV_CONTAINS 함수를 사용하고 2단계에서 제어 생성 시 '다중 선택 허용'을 선택해야 합니다(9.3부터 사용 가능).

예제 2: 시간 간격 제어

시계열을 구축하는 경우, 날짜 히스토그램 간격에 대한 변수 제어를 쉽게 추가할 수 있습니다.

1. 시계열에 대한 ES|QL 쿼리를 작성할 때 '제어 생성'을 클릭합니다. 간격 변수를 만들 때는 BUCKET 대신 TBUCKET 을(를) 사용하는 것이 좋습니다. '1시간', '1일'과 같은 더 읽기 쉬운 간격을 허용하기 때문입니다. TBUCKET 에 곧 자동 옵션이 추가되어 시간 범위에 자동으로 적응할 수 있게 됩니다.

2. 드롭다운 메뉴에서 옵션을 채울 간격을 정의합니다.

3. 드롭다운 메뉴에서 다른 간격을 선택하고 시각화가 어떻게 변하는지 확인합니다.

예제 3: 함수용 변수

1. '정적 값' 유형의 제어를 사용하여 변수를 생성하고 드롭다운 값에 함수 이름을 추가합니다. 함수를 대체하려면 '??...'로 시작하는 변수 이름을 사용하는 것이 중요합니다.

2. ES|QL 쿼리에 변수 이름을 포함합니다.

예제 4: 필드를 위한 변수

1. '정적 값' 유형의 제어를 사용하여 원하는 필드 이름을 작성할 수 있습니다. 필드에서 작동하려면 '??...'로 시작하는 변수 이름을 사용하는 것이 중요합니다.

2. 시각화 쿼리에서 원하는 위치에 변수를 참조합니다.

Discover의 변수 제어

변수 컨트롤은 단순한 대시보드 기능이 아닙니다. Discover의 ES|QL 편집기에서도 직접 사용할 수 있습니다. Discover에서 더 빠른 데이터 탐색 경험을 위한 제어를 생성하고, 이를 대시보드로 가져올 수 있으며, 그 반대로도 가능합니다.

기술적 세부 사항

이제 변수 제어에는 쿼리에서 참조할 수 있는 부분과 사용해야 하는 명명 접두사(값의 경우 "?...", 필드 또는 함수의 경우 "??...")와 같은 몇 가지 규칙이 있다는 것을 눈치채셨을 것입니다. 변수는 단순히 클라이언트 측에서 스트링 치환만 하는 것이 아니기 때문입니다. 실제로는 쿼리 언어 자체에서 1급 시민으로 처리됩니다(ES|QL에서 매개변수로 알려짐).

이 디자인은 몇 가지 큰 장점을 제공합니다. 첫째, Kibana는 각 변수의 맥락을 이해할 수 있어, 자동으로 구성 설정을 생성하고 미리 채울 수 있습니다. 또한 훨씬 더 안전합니다. 언어가 변수 입력의 유효성을 엄격하게 검사하여 악의적인 주입을 방지하고, 이상이 있을 경우 우아하게 오류를 처리합니다. 또한 복잡한 유효성 검사 및 오류 처리를 클라이언트가 아닌 서버로 전환하여 성능과 안정성을 향상합니다. 성능에 대한 참고 사항을 말씀드리자면, 빠른 쿼리는 대시보드보다 먼저 로드되기 대문에 쿼리가 느리면 전체 대시보드 성능에 영향을 미칠 수 있으므로 빠른 쿼리를 포함하는 변수를 작성하는 것이 가장 좋습니다.

물론, 이 아키텍처에는 현재로서 몇 가지 제약이 있습니다. 변수는 아직 필터링에 '모두' 옵션을 지원하지 않으며, 현재 LIKE 또는 FROM (데이터 소스 전환용)과 같은 특정 연산자와 함께 사용할 수 없습니다. 좋은 소식은? 이러한 기능을 추가하기 위해 열심히 노력하고 있습니다.

제어의 미래가 가져올 변화

여기서 멈추지 않습니다! 주목하고 있는 개선 사항 일부는 다음과 같습니다.

✨ 대시보드 어디에나 컨트롤을 배치할 수 있는 기능

✨ 제어 체인 연결 - 한 제어의 출력이 다음 제어의 입력이 되는 것

✨ 변수에 대한 '모든' 선택과 같은 더 나은 선택 옵션

✨ 새로운 제어 유형(검색 유형 제어 및 데이터 소스용 변수)

✨ 그리고 많은 분들이 요청했던 삶의 질을 향상하는 추가 기능(예: 일반 제어 사전 필터링)

아이디어나 피드백이 있으시면 언제든지 알려주시기 바랍니다.

요약

먼저 현황을 간략하게 설명하겠습니다. Elasticsearch는 강력한 벡터 데이터베이스로서, 풍부한 기능과 대규모 유사성 검색을 위한 뛰어난 성능을 제공하며 자리매김했습니다. 스칼라 양자화, Better Binary Quantization(BBQ), SIMD 벡터 연산, 그리고 DiskBBQ와 같은 디스크 효율적인 알고리즘을 통해 벡터 워크로드를 효율적이고 유연하게 관리할 수 있는 다양한 옵션을 제공합니다.

NVIDIA cuVS를 벡터 검색 작업을 위한 호출 가능한 모듈로 통합함으로써 벡터 색인화 성능과 효율성을 크게 향상해 대규모 벡터 워크로드를 보다 효과적으로 지원하는 것을 목표로 합니다.

당면 과제

고성능 벡터 데이터베이스를 구축하는 데 있어 매우 어려운 과제 중 하나는 벡터 인덱스, 즉 HNSW 그래프를 구성하는 것입니다. 인덱스 구축은 각 벡터가 다른 수많은 벡터와 비교되기 때문에 수백만, 심지어 수십억 개의 산술 연산으로 빠르게 진행됩니다. 또한 압축 및 병합과 같은 인덱스 수명 주기 작업은 색인화의 전체 컴퓨팅 오버헤드를 더 증가시킬 수 있습니다. 데이터 볼륨과 관련 벡터 임베딩이 기하급수적으로 증가함에 따라 대규모 병렬 처리와 높은 처리량의 연산을 위해 구축된 가속 컴퓨팅 GPU는 이러한 워크로드를 처리하는 데 최적의 위치에 있습니다.

Elasticsearch-GPU 플러그인 입력

NVIDIA cuVS는 GPU 가속 벡터 검색 및 데이터 클러스터링을 위한 오픈 소스 CUDA-X 라이브러리로, AI 및 추천 워크로드를 위한 빠른 인덱스 구축 및 임베딩 검색을 가능하게 합니다.

Elasticsearch는 커뮤니티가 개발하고 NVIDIA가 관리하는 오픈 소스 라이브러리인 cuvs-java를 통해 cuVS를 사용합니다. cuvs-java 라이브러리는 경량이며, cuVS C API를 기반으로 Panama Foreign Function을 사용하여 cuVS 기능을 관용적인 Java 방식으로 노출하면서도 최신 기술과 뛰어난 성능을 유지합니다.

cuvs-java 라이브러리는 새로운 Elasticsearch 플러그인에 통합되어 있습니다. 따라서 GPU에서의 벡터 색인화는 동일한 Elasticsearch 노드와 프로세스에서 외부 코드나 하드웨어를 프로비저닝할 필요 없이 수행할 수 있습니다. 인덱스 구축 중에 cuVS 라이브러리가 설치되고 GPU가 존재하며 구성된 경우 Elasticsearch는 GPU를 사용하여 벡터 색인화 프로세스를 가속화합니다. 벡터는 GPU에 전달되어 CAGRA 그래프를 구성합니다. 이 그래프는 HNSW 형식으로 변환되어 CPU에서 벡터를 즉시 검색할 수 있게 됩니다. 구축된 그래프의 최종 형식은 CPU에서 구축되는 것과 동일합니다. 이를 통해 Elasticsearch는 기본 하드웨어가 지원할 경우 높은 처리량의 벡터 색인화에 GPU를 활용할 수 있으며, 동시에 CPU 자원을 다른 작업(동시 검색, 데이터 처리 등)에 사용할 수 있습니다.

인덱스 구축 가속화

Elasticsearch에 GPU 가속화를 통합하는 과정에서 cuvs-java에 여러 가지 개선 사항이 적용되었으며, 특히 효율적인 데이터 입출력 및 함수 호출에 중점을 두었습니다. 핵심적인 개선 사항 중 하나는 cuVSMatrix를 사용하여 Java 힙, 오프힙 또는 GPU 메모리에 저장된 벡터를 투명하게 모델링하는 것입니다. 이를 통해 데이터가 메모리와 GPU 간에 효율적으로 이동하여 수십억 개의 벡터를 불필요하게 복사하는 것을 방지할 수 있습니다.

이러한 기본 제로 카피 추상화 덕분에 GPU 메모리로의 전송과 그래프 검색이 모두 직접 이루어질 수 있습니다. 색인화하는 동안 벡터는 먼저 Java 힙의 메모리에 버퍼링된 다음 GPU로 전송되어 CAGRA 그래프를 구성합니다. 그 후 그래프는 GPU에서 검색되어 HNSW 형식으로 변환된 후 디스크에 유지됩니다.

병합 시점에 벡터는 이미 디스크에 저장되어 있으므로 Java 힙을 완전히 우회합니다. 인덱스 파일은 메모리 맵핑 방식으로 처리되며 데이터는 GPU 메모리로 직접 전송됩니다. 또한 이 설계는 float32 또는 int8과 같은 다양한 비트 폭을 쉽게 수용할 수 있으며 다른 양자화 방식으로도 자연스럽게 확장됩니다.

자, 그럼 성능은 어떨까요?

수치를 살펴보기 전에, 약간의 배경 설명이 필요합니다. Elasticsearch에서 세그먼트 병합은 보통 색인 과정 중 백그라운드에서 자동으로 실행되기 때문에, 이를 단독으로 분리해 벤치마크하기가 어렵습니다. 재현 가능한 결과를 얻기 위해, 이번에는 강제 병합을 사용하여 통제된 실험 환경에서 세그먼트 병합을 명시적으로 트리거했습니다. 강제 병합은 백그라운드 병합과 동일한 기본 병합 작업을 수행하므로, 실제 색인 워크로드에서는 정확한 향상 폭이 다를 수 있지만, 성능 개선 효과를 가늠하는 유용한 지표로 볼 수 있습니다.

이제 수치를 확인해 보겠습니다.

초기 벤치마크 결과는 매우 희망적입니다. 로컬로 연결된 NVMe 저장 공간이 있는 AWS g6.4xlarge 인스턴스에서 벤치마크를 실행했습니다. Elasticsearch의 단일 노드는 기본 최적의 색인화 스레드 수(8개 - 물리적 코어당 1개)를 사용하고 병합 스로틀링을 비활성화하도록 구성되었습니다(빠른 NVMe 디스크에는 적용하기 어렵습니다).

데이터 세트에는 OpenAI Rally 벡터 트랙에서 가져온 1,536차원의 260만 개 벡터를 사용했으며, base64 스트링으로 인코딩하고 float32 hnsw로 색인화했습니다. 모든 시나리오에서 구성된 그래프는 최대 95%의 재현율을 달성했습니다. 결과는 다음과 같습니다.

• 색인화 처리량: 인메모리 버퍼 플러시 중 그래프 구성을 GPU로 이동하여 처리량이 약 12배 증가합니다.
• 강제 병합: 색인화가 완료된 후에도 GPU는 세그먼트 병합을 계속 가속화하여 강제 병합 단계의 속도를 최대 7배까지 높입니다.

• CPU 사용량: 그래프 구성을 GPU로 오프로드하면 평균 및 최대 CPU 사용량이 많이 감소합니다. 아래 그래프는 색인화 및 병합 중 CPU 사용량을 보여주며, 이러한 작업이 GPU에서 실행될 때 GPU 작업량이 얼마나 낮아지는지를 강조합니다. GPU 색인화 중 CPU 사용률이 낮아지면 CPU 사이클이 확보되어 검색 성능 향상에 활용할 수 있습니다.

• 재현율: CPU와 GPU 실행 간의 정확도는 사실상 동일하지만, GPU로 구축된 그래프는 재현율이 약간 더 높습니다.

가격 측면에서 비교

앞선 비교에서는 의도적으로 동일한 하드웨어를 사용했으며 유일한 차이점은 색인 과정에서 GPU를 사용했는지 여부였습니다. 이 설정은 순수 연산 성능의 영향을 분리하여 파악하는 데 유용하지만 비용 관점에서의 비교도 가능합니다.

GPU 가속 구성과 거의 동일한 시간당 요금으로 CPU 전용 구성을 프로비저닝할 수 있습니다. 이 경우 비교 가능한 CPU 및 메모리 리소스가 약 두 배(32 vCPU(AMD EPYC), 64GB RAM)로 제공되며 색인 스레드 수를 16개로 두 배 늘릴 수 있습니다.

공정하고 일관된 비교를 위해 GPU를 명시적으로 비활성화한 상태로 AWS g6.8xlarge 인스턴스에서 CPU 전용 실험을 수행했습니다. 이를 통해 다른 모든 하드웨어 특성을 동일하게 유지하면서 GPU 가속과 CPU 전용 색인 간의 비용 대비 성능 트레이드오프를 평가할 수 있었습니다.

예상대로 더 강력한 CPU 인스턴스는 위 섹션의 벤치마크와 비교했을 때 향상된 성능을 보여줍니다. 그러나 이 더 강력한 CPU 인스턴스를 원래의 GPU 가속 결과와 비교해 보면 GPU는 여전히 상당한 성능 향상을 제공합니다. 색인화 처리량에서 약 5배, 강제 병합에서 약 6배의 성능 향상을 보이며, 동시에 최대 95%의 재현율을 달성하는 그래프를 구축할 수 있습니다.

결론

엔드 투 엔드 시나리오에서 NVIDIA cuVS를 사용한 GPU 가속화는 색인화 처리량을 거의 12배 향상하고 강제 병합 지연 시간을 7배 단축하는 동시에 CPU 사용률을 크게 낮춥니다. 이는 벡터 색인화 및 병합 워크로드가 GPU 가속화를 통해 상당한 성능 향상을 얻을 수 있음을 보여줍니다. 비용을 고려한 비교에서도 GPU 가속화는 색인화 처리량을 약 5배, 강제 병합 작업 속도를 약 6배 향상하는 등 상당한 성능 향상을 제공합니다.

GPU 가속 벡터 색인화는 현재 Elasticsearch 9.3의 기술 미리 보기로 계획되어 있으며, 2026년 초에 출시될 예정입니다.

더 많은 소식을 기대해 주세요.

ES|QL을 통해 데이터 분석 워크플로우를 혁신할 Elasticsearch 9.2의 기능을 살펴보겠습니다.

데이터 상관 관계 혁신: 더 스마트하고 빠르며 유연한 조회 조인

ES|QL의 LOOKUP JOIN 명령은 Elasticsearch 9.2에서 상당한 변화를 거쳐 효율성과 활용도가 크게 향상되었습니다. LOOKUP JOIN은 ES|QL 쿼리 결과 테이블의 데이터를 지정된 조회 모드 인덱스의 일치하는 레코드와 결합합니다. 조인 필드의 일치하는 값을 기준으로 조회 인덱스의 필드를 결과 테이블에 새로운 열로 추가합니다. 이전에는 데이터 조인이 단일 필드와 단순 동등성으로 제한되었지만, 이제는 그렇지 않습니다. 이러한 향상된 기능을 통해 복잡한 데이터 상관관계 시나리오를 손쉽게 처리할 수 있습니다.

Lookup Join의 주요 개선 사항은 다음과 같습니다:

• 다중 필드 조인: 여러 필드를 쉽게 조인할 수 있습니다. 예를 들어 application_logs 와(과)service_registry 을(를)service_name, environment, 버전을 기준으로 조인하려면 다음과 같이 합니다. version:

FROM application_logs
| LOOKUP JOIN service_registry ON service_name, environment, version

• 표현식으로 복잡한 조인 술어 활용(기술 미리 보기):

더 이상 단순한 등식에 국한되지 않습니다. LOOKUP JOIN을 사용하면 상관관계에 대한 여러 기준을 지정하고 ==, !=, <, >, <=, >= 등 다양한 이항 연산자를 사용할 수 있습니다. 즉, 고도로 정교한 조인 조건을 생성하여 데이터에 대해 훨씬 더 정교한 질문을 던질 수 있습니다.

예시 1: 서비스별 SLA 임계값을 사용하여 애플리케이션 메트릭 찾기

FROM application_metrics
| LOOKUP JOIN sla_thresholds
      ON service_name == sla_service AND response_time > sla_response_time

예시 2: 이 쿼리는 시간에 따라 변동하는 지역별 가격 정책을 기반으로 납부 금액을 계산합니다. 복잡한 날짜 범위와 등식 조건을 기반으로 세 개의 데이터 세트를 결합하여 최종 due_amount을(를) 계산합니다. 두 번째 LOOKUP JOIN은 meter_readings 인덱스의 measurement_date 필드와 customers 인덱스의 region_id 필드를 사용하여 pricing_policies 인덱스에 조인하고 특정 region 및 measurement_date에 대한 올바른 가격 정책을 찾습니다.

FROM meter_readings
| LOOKUP JOIN customers
      ON meter_id
| LOOKUP JOIN pricing_policies
      ON
        region_id == region AND
          measurement_date >= policy_begin_date AND
          measurement_date < policy_end_date
| EVAL due_amount = (kwh_consumed * rate_per_kwh + base_charge) * (1 + tax_rate)
| EVAL period = policy_name
| KEEP customer_name, period, due_amount, measurement_date, kwh_consumed,
    rate_per_kwh, base_charge, tax_rate
| SORT measurement_date

• 필터링된 조인의 대규모 성능 향상

조회 테이블 조건을 사용하여 필터링되는 '확장 조인'의 성능을 개선했습니다. 확장 조인은 입력 행당 여러 개의 일치 항목을 생성하여 큰 중간 결과 세트를 생성할 수 있습니다. 이러한 행 중 상당수가 후속 필터에 의해 삭제되는 경우 상황은 더 악화됩니다. 9.2에서는 조회 데이터에 필터를 적용할 때 불필요한 행을 필터링하여 삭제될 행의 처리를 방지함으로써 이러한 조인을 최적화합니다. 때에 따라 이러한 조인은 최대 1,000배 더 빨라질 수 있습니다.

이러한 최적화는 조회가 초기에 많은 잠재적 일치 항목을 생성할 수 있는 '확장 조인'을 처리할 때 매우 중요합니다. 지능적으로 필터를 적용하면 관련 데이터만 처리되어 쿼리 실행 시간이 크게 단축되고 방대한 데이터 세트에 대한 실시간 분석이 가능해집니다. 즉, 매우 크거나 복잡한 조인 작업에서도 훨씬 빠르게 인사이트를 얻을 수 있습니다.

LOOKUP JOIN 클러스터 간 검색(CCS) 호환성:

LOOKUP JOIN이 8.19와 9.1 버전에서 정식 출시되었을 당시에는 클러스터 간 검색(CCS) 지원이 부족했습니다. 여러 클러스터에서 운영되는 조직의 경우 LOOKUP JOIN은 이제 9.2에서 CCS와 완벽하게 통합됩니다. 조인을 수행하려는 모든 원격 클러스터에 조회 인덱스를 추가하기만 하면 ES|QL이 자동으로 이러한 원격 조회 인덱스를 활용하여 원격 데이터와 조인합니다. 이를 통해 분산 데이터 분석이 간소화되고 전체 Elasticsearch 배포 환경에서 일관된 데이터 보강이 보장됩니다.

이러한 개선 사항을 통해 전례 없는 정밀도, 속도, 용이성으로 다양한 데이터 세트를 상호 연관시켜 복잡한 해결 방법이나 사전 처리 단계 없이 더 깊고 실행 가능한 인사이트를 발견할 수 있습니다.

조회 인덱스용 Kibana Discover UX를 사용해 간편하게 데이터 보강

데이터 보강은 간단해야 하며, 장애물이 되어서는 안 됩니다. Kibana의 Discover에서 조회 인덱스를 생성하고 관리하기 위해 새롭고 환상적인 사용자 환경을 도입했습니다.

직관적인 워크플로우: Discover의 포괄적인 자동 완성 기능은 ES|QL 편집기에서 조회 인덱스와 조인 필드를 제안하여 프로세스를 안내해 주므로, 업로드한 데이터를 기존 인덱스와 매우 쉽게 연결할 수 있습니다. 존재하지 않는 조회 인덱스 이름을 입력하면 클릭 한 번으로 조회 편집기에 바로 액세스하여 인덱스를 생성할 수 있습니다. 기존 조회 인덱스 이름을 입력하면 다음과 같이 편집 옵션을 제안해 드립니다.

인라인 관리(CRUD): Discover에서 직접 인라인 편집 기능(생성, 읽기, 업데이트, 삭제)을 사용하여 참조 데이터 세트를 최신 상태로 유지하세요.

간편한 파일 업로드: 이제 CSV와 같은 파일을 Discover 내에서 직접 업로드하고 LOOKUP JOIN에서 즉시 사용할 수 있습니다. Kibana의 다른 영역을 오가며 컨텍스트를 전환할 필요가 없습니다!

사용자 ID를 이름에 매핑하거나 비즈니스 메타데이터를 추가하거나 정적 참조 파일을 조인할 때, 이 기능은 데이터 보강을 대중화하고 모든 사용자가 조인 기능을 직접 사용할 수 있도록 합니다. 빠르고 간편하며 모든 것이 한 곳에서 가능합니다.

컨텍스트 보존: INLINE STATS 소개 (기술 미리 보기)

데이터 집계는 중요하지만, 때로는 집계된 데이터를 원본 데이터와 함께 확인해야 할 때가 있습니다. 기술 미리 보기 기능으로 인라인 통계를 소개하게 되어 기쁩니다.

STATS 명령은 입력 필드를 집계된 출력으로 대체하지만, INLINE STATS 명령은 원래 입력 필드를 그대로 유지하고 집계된 새 필드를 추가합니다. 이는 집계 후 원래 입력 필드에서 추가 작업을 수행할 수 있게 하여 보다 지속적이고 유연한 워크플로우를 제공합니다.

예를 들어 개별 비행 행을 유지하면서 평균 비행 거리를 계산하려면 다음을 수행합니다.

FROM kibana_sample_data_flights
 | KEEP Carrier, Dest, DistanceMiles
 | INLINE STATS avgDist = ROUND(AVG(DistanceMiles))
       BY Dest
 | WHERE DistanceMiles > avgDist

이 쿼리에서는 그룹화 기준으로 사용된 해당 Dest(ination)을(를) 사용하여 각 행에 avgDist을(를) 추가한 다음, 항공편 정보 열이 남아 있으므로 평균보다 거리가 먼 항공편으로 결과를 필터링할 수 있습니다.

ES|QL의 시계열 지원 (기술 미리 보기)

Elasticsearch는 시계열 데이터 스트림을 사용하여 메트릭을 저장합니다. TS 소스 명령을 통해 ES|QL에서 시계열 집계에 대한 지원을 추가하고 있습니다. 이 기능은 Elastic Cloud Serverless 및 9.2 기본 버전에서 기술 미리 보기로 제공됩니다.

시계열 분석은 주로 시간 버킷에 대한 메트릭 값을 하나 이상의 필터링 차원으로 분할하여 요약하는 집계 쿼리를 기반으로 합니다. 대부분의 집계 쿼리는 2단계 처리 방식을 사용하는데, (a) 시계열별 값을 요약하는 내부 집계 함수와 (b) 시계열 전반에 걸쳐 (a)의 결과를 결합하는 외부 집계 함수가 있습니다.

TS 소스 명령어와 STATS을(를) 결합하면 시계열 데이터에 대한 쿼리를 간결하면서도 효과적으로 표현할 수 있습니다. 좀 더 구체적으로 호스팅 및 시간당 총 요청 비율을 계산하는 다음 예시를 살펴보겠습니다.

TS my_metrics
| WHERE @timestamp > NOW() - 1 day
| STATS SUM(RATE(requests))
      BY host, TBUCKET(1h)

이 경우 시계열 집계 함수 RATE이(가) 먼저 시계열 및 시간별로 평가됩니다. 그런 다음 SUM을(를) 사용하여 생성된 부분 집계를 결합하여 호스팅 및 시간당 최종 집계 값을 계산합니다.

사용 가능한 시계열 집계 함수 목록은 여기에서 확인하세요. 카운터 비율이 이제 지원되며, 이는 카운터 처리를 위한 가장 중요한 집계 함수라고 할 수 있습니다.

TS 소스 명령은 STATS와(과) 결합하여 사용할 수 있도록 설계되었으며, 시계열 집계를 효율적으로 지원하도록 실행이 최적화되었습니다. 예를 들어 데이터는 STATS(으)로 이동하기 전에 정렬됩니다. FORK 또는 INLINE STATS와(과) 같은 시계열 데이터 또는 그 순서를 보강하거나 변경할 수 있는 처리 명령은 현재 TS와(과) STATS 사이에 허용되지 않습니다. 이 제한은 향후 해제될 수 있습니다.

STATS 표 형식 출력은 해당 명령을 사용하여 추가로 처리할 수 있습니다. 예를 들어 다음 쿼리는 호스팅 및 시간당 평균 cpu_usage와(과) 호스팅당 최대값의 비율을 계산합니다.

TS my_metrics
| STATS avg_usage = AVG(AVG_OVER_TIME(cpu_usage))
      BY host, time_bucket = TBUCKET(1h)
| INLINE STATS max_avg_usage = MAX(avg_usage)
      BY host
| EVAL ratio = avg_usage / max_avg_usage
| KEEP host, time_bucket, ratio
| SORT host, time_bucket DESC

시계열 데이터는 Lucene doc 값으로 구동되는 기본 열 형식 저장 공간 엔진에 저장됩니다. TS 명령은 ES|QL 컴퓨팅 엔진을 통해 벡터화된 쿼리 실행 기능을 추가합니다. 동급 DSL 쿼리에 비해 쿼리 성능이 10배 이상 향상되는 경우가 많습니다. 향후 자세한 아키텍처 및 성능 분석을 제공할 예정이니 기대해 주시기 바랍니다.

툴킷 확장: 새로운 ES|QL 함수

스트링 조작: 더욱 강력한 텍스트 및 URL 처리를 위해 CONTAINS, MV_CONTAINS, URL_ENCODE, URL_ENCODE_COMPONENT, URL_DECODE을(를) 제공합니다.

시계열 및 위치 정보: 유연한 시간 버킷을 위한 TBUCKET, 벡터 연산을 위한 TO_DENSE_VECTOR, 고급 위치 기반 분석을 위한 ST_GEOHASH, ST_GEOTILE, ST_GEOHEX, TO_GEOHASH, TO_GEOTILE, TO_GEOHEX 와 같은 포괄적인 위치 정보 함수 세트를 제공합니다.

날짜 형식: 가독성 높은 날짜 표현을 위해 DAY_NAME, MONTH_NAME을 제공합니다.

이러한 함수는 ES|QL 내에서 직접 데이터를 조작하고 분석할 수 있는 더욱 풍부한 도구 세트를 제공합니다.

내부적인 개선을 통한 성능 및 효율성 향상

Elasticsearch 9.2에는 강조된 기능 외에도 ES|QL 전반에 걸쳐 다양한 성능 최적화가 포함되어 있습니다. RLIKE (LIST) 함수가 여러 개의 유사한 RLIKE 쿼리를 대체하는 경우 푸시다운을 사용하여 속도를 높였습니다. RLIKE (LIST)를 사용하면 이러한 쿼리를 단일 Automaton로 병합하여 여러 Automaton 대신 하나의 Automaton를 적용할 수 있습니다. 또한 인덱스 정렬을 통해 키워드 필드를 더 빠르게 로딩하고 일반적인 쿼리를 최적화하여 ES|QL 쿼리를 그 어느 때보다 효율적으로 실행할 수 있도록 개선했습니다.

오늘 바로 시작해 보세요!

Elasticsearch 9.2는 ES|QL의 획기적인 도약을 의미하며, 데이터 분석 워크플로우에 전례 없는 지원과 유연성을 제공합니다. 이러한 새로운 기능을 살펴보고 그 차이를 경험해 보시기 바랍니다.

Elasticsearch 9.2의 모든 변경 사항과 향상된 기능에 대한 전체 목록은 공식 릴리즈 노트에서 확인하세요. 쿼리 작업을 즐겨보세요!

맞춤형 커넥터를 사용하면 기존 ChatGPT 커넥터를 Elasticsearch와 같은 추가 데이터 소스와 결합하여 포괄적인 답변을 얻을 수 있습니다.

이문서에서는 내부 GitHub 문제와 풀 요청에 대한 정보를 포함하는 Elasticsearch 인덱스에 ChatGPT를 연결하는 MCP 서버를 구축합니다. 이 기능을 통해 Elasticsearch 데이터를 사용하여 자연어 쿼리에 응답할 수 있습니다.

Google Colab에서 FastMCP를 사용하여 MCP 서버를 배포하고, ngrok을 통해 ChatGPT가 연결할 수 있는 공개 URL을 얻어 복잡한 인프라 설정을 간소화합니다.

MCP와 에코시스템에 대한 종합적인 개요는 MCP의 현재 상태를 참조하세요.

필수 구성 요소

시작하려면 다음이 필요합니다.

• Elasticsearch 클러스터 (8.X 이상)
• 인덱스에 대한 읽기 권한이 있는 Elasticsearch API 키
• Google 계정 (Google Colab용)
• Ngrok 계정 (무료 요금제 사용 가능)
• 프로/엔터프라이즈/비즈니스 또는 에듀 요금제로 등록된 ChatGPT 계정

ChatGPT MCP 커넥터 요구사항 이해하기

ChatGPT MCP 커넥터를 사용하려면 search 와 fetch, 두 가지를 구현해야 합니다. 자세한 내용은 OpenAI 문서를 참조하세요.

검색 툴

사용자 쿼리를 기반으로 Elasticsearch 인덱스에서 관련 결과 목록을 반환합니다.

수신 내용:

• 사용자의 자연어 쿼리가 포함된 단일 스트링입니다.
• 예: 'Elasticsearch 마이그레이션과 관련된 문제 찾기'

반환값: 

• 결과 객체 배열을 포함하는 result 키를 가진 객체입니다. 각 결과에는 다음이 포함됩니다.
  • id - 고유 문서 식별자
  • title - 이슈 또는 PR 제목
  • url - 문제/PR에 대한 링크

구현에서:

return {
    "results": [
        {
            "id": "PR-612",
            "title": "Fix memory leak in WebSocket notification service",
            "url": "https://internal-git.techcorp.com/pulls/612"
        },
        # ... more results
    ]
}

가져오기 도구

특정 문서의 전체 내용을 가져옵니다.

수신 내용:

• 검색 결과에서 Elasticsearch 문서 ID를 포함하는 단일 스트링
• 예: 'PR-578의 세부 정보를 가져와'

반환값:

• 다음 항목을 포함한 완전한 문서 객체입니다.
  • id - 고유 문서 식별자
  • title - 이슈 또는 PR 제목
  • text - 전체 문제/PR 설명 및 세부 정보
  • url - 문제/PR에 대한 링크
  • type - 문서 유형(문제, pull_request)
  • status - 현재 상태(오픈, 진행 중, 해결 완료)
  • priority - 우선순위 수준(낮음, 중간, 높음, 긴급)
  • assignee - 문제/PR 담당자
  • created_date - 생성된 시점
  • resolved_date - 해결된 시점(해당되는 경우)
  • labels - 문서에 연결된 태그
  • related_pr - 관련 풀 요청 ID

return {
    "id": "PR-578",
    "title": "Security hotfix: Patch SQL injection vulnerabilities",
    "text": "Description: CRITICAL SECURITY FIX for ISSUE-1889. Patches SQL...",
    "url": "https://internal-git.techcorp.com/pulls/578",
    "type": "pull_request",
    "status": "closed",
    "priority": "critical",
    "assignee": "sarah_dev",
    "created_date": "2025-09-19",
    "resolved_date": "2025-09-19",
    "labels": "security, hotfix, sql",
    "related_pr": null
}

참고: 이 예에서는 모든 필드가 루트 레벨에 있는 플랫 구조를 사용합니다. OpenAI 요구 사항은 유연하며 중첩된 메타데이터 개체도 지원합니다.

GitHub 이슈 및 PR 데이터 세트

이 튜토리얼에서는 문제와 풀 요청이 포함된 내부 GitHub 데이터 집합을 사용합니다. 이는 ChatGPT를 통해 비공개 내부 데이터를 쿼리하는 시나리오입니다.

데이터 세트는 여기에서 찾을 수 있습니다. 그리고 벌크 API를 사용해 데이터의 색인을 업데이트할 것입니다.

이 데이터 세트에는 다음이 포함되어 있습니다.

• 설명, 상태, 우선순위 및 담당자와 관련된 문제
• 코드 변경, 리뷰, 배포 정보가 포함된 풀 요청
• 문제와 PR 간의 관계 (예: PR-578이 ISSUE-1889를 수정함)
• 라벨, 날짜 및 기타 메타데이터

인덱스 매핑

인덱스는 매핑을 사용해 ELSER와의 하이브리드 검색을 지원합니다. text_semantic은 시맨틱 검색에 사용되며, 다른 필드는 키워드 검색을 지원합니다.

{
  "mappings": {
    "properties": {
      "id": {
        "type": "keyword"
      },
      "title": {
        "type": "text"
      },
      "text": {
        "type": "text"
      },
      "text_semantic": {
        "type": "semantic_text",
        "inference_id": ".elser-2-elasticsearch"
      },
      "url": {
        "type": "keyword"
      },
      "type": {
        "type": "keyword"
      },
      "status": {
        "type": "keyword"
      },
      "priority": {
        "type": "keyword"
      },
      "assignee": {
        "type": "keyword"
      },
      "created_date": {
        "type": "date",
        "format": "iso8601"
      },
      "resolved_date": {
        "type": "date",
        "format": "iso8601"
      },
      "labels": {
        "type": "keyword"
      },
      "related_pr": {
        "type": "keyword"
      }
    }
  }
}

MCP 서버 구축

저희 MCP 서버는 더 나은 결과를 위해 하이브리드 검색을 사용하여 시맨틱과 텍스트 매칭을 결합하는 OpenAI 사양을 따르는 두 가지 도구를 구현합니다.

검색 툴

RRF(상호 순위 융합)을 사용하여 의미론적 검색과 텍스트 매칭을 결합한 하이브리드 검색을 사용합니다.

@mcp.tool()
    async def search(query: str) -> Dict[str, List[Dict[str, Any]]]:
        """
        Search for internal issues and PRs using hybrid search (semantic + text with RRF).
        Returns list with id, title, and url per OpenAI spec.
        """
        if not query or not query.strip():
            return {"results": []}

        logger.info(f"Searching for: '{query}'")

        try:
            # Hybrid search with RRF (Reciprocal Rank Fusion)
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                size=10,
                source=["id", "title", "url", "type", "priority"],
                retriever={
                    "rrf": {
                        "retrievers": [
                            {
                                # Semantic search with ELSER
                                "standard": {
                                    "query": {
                                        "semantic": {
                                            "field": "text_semantic",
                                            "query": query
                                        }
                                    }
                                }
                            },
                            {
                                # Text search (BM25) for keyword matching
                                "standard": {
                                    "query": {
                                        "multi_match": {
                                            "query": query,
                                            "fields": [
                                                "title^3",
                                                "text^2",
                                                "assignee^2",
                                                "type",
                                                "labels",
                                                "priority"
                                            ],
                                            "type": "best_fields",
                                            "fuzziness": "AUTO"
                                        }
                                    }
                                }
                            }
                        ],
                        "rank_window_size": 50,
                        "rank_constant": 60
                    }
                }
            )

            results = []
            if response and 'hits' in response:
                for hit in response['hits']['hits']:
                    source = hit['_source']
                    results.append({
                        "id": source.get('id', hit['_id']),
                        "title": source.get('title', 'Unknown'),
                        "url": source.get('url', '')
                    })

            logger.info(f"Found {len(results)} results")
            return {"results": results}

        except Exception as e:
            logger.error(f"Search error: {e}")
            raise ValueError(f"Search failed: {str(e)}")

주요 사항:

• RRF를 사용한 하이브리드 검색: 시맨틱 검색(ELSER)과 텍스트 검색(BM25)을 결합하여 더 나은 결과를 제공합니다.
• 다중 일치 쿼리: 부스팅(title^3, text^2, assignee^2)을 사용하여 여러 필드에 걸쳐 검색합니다. 캐럿 기호(^)는 관련성 점수를 곱하여 콘텐츠보다 제목의 일치 항목에 우선순위를 부여합니다.
• 퍼지 매칭: fuzziness: AUTO는 대략적인 매칭을 허용함으로써 오타와 맞춤법 오류를 처리합니다.
• 상호 순위 결합(RRF) 파라미터 튜닝:
  • rank_window_size: 50 - 병합하기 전에 각 검색기(시맨틱 및 텍스트)에서 고려할 상위 결과의 수를 지정합니다.
  • rank_constant: 60 - 이 값은 개별 결과 집합의 문서가 최종 순위 결과에 미치는 영향을 결정합니다.
• 필수 필드만 반환: OpenAI 사양에 따라 id, title, url 만 반환되며, 불필요한 추가 필드를 노출하지 않습니다.

가져오기 도구

문서가 있는 경우 문서 ID로 문서 세부 정보를 검색합니다.

@mcp.tool()
    async def fetch(id: str) -> Dict[str, Any]:
        """
        Retrieve complete issue/PR details by ID.
        Returns id, title, text, url.
        """
        if not id:
            raise ValueError("ID is required")

        logger.info(f"Fetching: {id}")

        try:
            # Search by the 'id' field (not _id) since IDs are stored as a field
            response = es_client.search(
                index=ELASTICSEARCH_INDEX,
                body={
                    "query": {
                        "term": {
                            "id": id  # Search by your custom 'id' field
                        }
                    },
                    "size": 1
                }
            )

            if not response or not response['hits']['hits']:
                raise ValueError(f"Document with id '{id}' not found")

            hit = response['hits']['hits'][0]
            source = hit['_source']

            result = {
                "id": source.get('id', id),
                "title": source.get('title', 'Unknown'),
                "text": source.get('text', ''),
                "url": source.get('url', ''),
                "type": source.get('type', ''),
                "status": source.get('status', ''),
                "priority": source.get('priority', ''),
                "assignee": source.get('assignee', ''),
                "created_date": source.get('created_date', ''),
                "resolved_date": source.get('resolved_date', ''),
                "labels": source.get('labels', ''),
                "related_pr": source.get('related_pr', '')
            }

            logger.info(f"Fetched: {result['title']}")
            return result

        except Exception as e:
            logger.error(f"Fetch error: {e}")
            raise ValueError(f"Failed to fetch '{id}': {str(e)}")

주요 사항:

• 문서 ID 필드로 검색: 사용자 정의 id 필드에서 용어 쿼리를 사용합니다.
• 전체 문서 반환: 모든 콘텐츠가 포함된 전체 text 필드를 포함합니다.
• 플랫 구조: 모든 필드가 루트 수준에 있으며, Elasticsearch의 문서 구조와 일치합니다.

Google Colab에 배포

Google Colab을 사용하여 MCP 서버를 실행하고 ngrok을 사용해 외부에 공개함으로써 ChatGPT가 연결할 수 있도록 합니다.

1단계: Google Colab 노트북 열기

사전 구성된 Elasticsearch MCP for ChatGPT 노트북에 액세스합니다.

2단계: 자격 증명을 구성하세요

세 가지 정보를 준비해야 합니다.

• Elasticsearch URL: Elasticsearch 클러스터 URL입니다.
• Elasticsearch API 키: API 키로 인덱스에 대한 읽기 액세스 권한을 부여합니다.
• Ngrok 인증 토큰: ngrok에서 무료로 제공하는 토큰입니다. ngrok을 사용하여 MCP URL을 인터넷에 노출하여 ChatGPT가 연결할 수 있도록 합니다.

ngrok 토큰 받기

1. ngrok에서 무료 계정 가입
2. ngrok 대시보드로 이동
3. 인증 토큰을 복사하세요

Google Colab에 시크릿 추가

Google Colab 노트북에서:

1. 왼쪽 사이드바에서 키 아이콘을 클릭하여 시크릿을 엽니다.
2. 이 세 가지 시크릿을 추가합니다.

ELASTICSEARCH_URL=https://your-cluster.elastic.com:443
ELASTICSEARCH_API_KEY=your-api-key
NGROK_TOKEN=your-ngrok-token

3. 각 시크릿에 대한 노트북 접근 활성화

3단계: 노트북 실행

1. 런타임을 클릭한 다음 모두 실행을 클릭하여 모든 셀을 실행합니다.
2. 서버가 시작될 때까지 기다립니다(약 30초).
3. 공개 ngrok URL을 표시하는 출력을 찾습니다.

4. 출력은 다음과 같이 표시됩니다.

ChatGPT에 연결

이제 MCP 서버를 ChatGPT 계정에 연결합니다.

1. ChatGPT를 열고 설정으로 이동합니다.
2. 커넥터로 이동합니다.프로 계정을 사용하는 경우 커넥터에서 개발자 모드를 사용 설정해야 합니다.

ChatGPT 엔터프라이즈 또는 비즈니스 버전을 사용하는 경우, 커넥터를 작업 환경에 게시해야 합니다.

3. 만들기를 클릭합니다.

참고: 비즈니스, 엔터프라이즈, 에듀 작업 공간에서는 작업 공간 소유자, 관리자 및 해당 설정이 활성화된 사용자(엔터프라이즈/에듀)만 사용자 정의 커넥터를 추가할 수 있습니다. 일반 회원 역할을 가진 사용자는 사용자 정의 커넥터를 직접 추가할 수 없습니다.

소유자 또는 관리자 사용자가 커넥터를 추가하고 활성화하면 작업 공간의 모든 구성원이 이를 사용할 수 있습니다.

4. 필요한 정보를 입력하고 /sse/로 끝나는 ngrok URL을 입력합니다. 'sse"' 뒤의 '/'에 주의하세요. 이것 없이는 작동하지 않습니다.

• 이름: Elasticsearch MCP
• 설명: GitHub 내부 정보를 검색하고 가져오기 위한 사용자 정의 MCP입니다.

5. 생성 을 눌러 사용자 정의 MCP를 저장하세요.

서버가 실행 중이면 즉시 연결됩니다. Elasticsearch API 키가 서버에 구성되어 있으므로 추가 인증이 필요하지 않습니다.

MCP 서버 테스트

질문을 하기 전에 ChatGPT가 사용할 커넥터를 선택해야 합니다.

프롬프트 1: 문제 검색

질문: 'Elasticsearch 마이그레이션과 관련된 문제를 찾아'라고 요청하고 작업 도구 호출을 확인하세요.

ChatGPT가 사용자의 쿼리를 사용하여 search 도구를 호출합니다. 사용 가능한 도구를 찾고 Elasticsearch 도구를 호출할 준비를 하며, 도구에 대해 조치를 취하기 전에 사용자에게 확인하는 것을 볼 수 있습니다.

도구 호출 요청:

{
  "query": "Elasticsearch migration issues"
}

도구 응답:

{
  "results": [
    {
      "id": "PR-598",
      "title": "Elasticsearch 8.x migration - Application code changes",
      "url": "https://internal-git.techcorp.com/pulls/598"
    },
    {
      "id": "ISSUE-1712",
      "title": "Migrate from Elasticsearch 7.x to 8.x",
      "url": "https://internal-git.techcorp.com/issues/1712"
    },
    {
      "id": "RFC-045",
      "title": "Design Proposal: Microservices Migration Architecture",
      "url": "https://internal-git.techcorp.com/rfcs/045"
    }
    // ... 7 more results
  ]
}

ChatGPT는 결과를 처리하여 자연스러운 대화 형식으로 표시합니다.

비하인드 스토리

프롬프트: 'Elasticsearch 마이그레이션 관련 문제를 찾아'

1. ChatGPT 호출 search(“Elasticsearch migration”)

2. Elasticsearch가 하이브리드 검색 수행

• 시맨틱 검색은 '업그레이드' 및 '버전 호환성'과 같은 개념을 이해합니다.
• 텍스트 검색은 'Elasticsearch' 및 '마이그레이션'과 정확히 일치하는 결과를 찾습니다.
• RRF는 두 가지 접근 방식의 결과를 결합하고 순위를 매깁니다.

3. id, title와 일치하는 상위 10개의 이벤트를 반환합니다, url

4. ChatGPT는 'ISSUE-1712: Elasticsearch 7.x에서 8.x로 마이그레이션'을 가장 관련성 있는 결과로 식별합니다

프롬프트 2: 전체 세부 정보 확인

문의: 'ISSUE-1889의 세부 정보를 보여줘'

ChatGPT는 사용자가 특정 문제에 대한 자세한 정보를 원한다는 것을 인식하고 fetch 도구를 호출한 후, 도구에 대해 조치를 취하기 전에 사용자에게 확인합니다.

도구 호출 요청:

{
  "id": "ISSUE-1889"
}

도구 응답:

{
  "id": "ISSUE-1889",
  "title": "SQL injection vulnerability in search endpoint",
  "text": "Description: Security audit identified SQL injection vulnerability in /api/v1/search endpoint. User input from query parameter is not properly sanitized before being used in raw SQL query. Severity: HIGH - Immediate action required Affected Code: - File: services/search/query_builder.py - Line: 145-152 - Issue: String concatenation used instead of parameterized queries Investigation: - @security_team_alice: Confirmed exploitable with UNION-based injection - @sarah_dev: Checking all other endpoints for similar patterns - @john_backend: Found 3 more instances in legacy codebase Remediation: - Rewrite using SQLAlchemy ORM or parameterized queries - Add input validation and sanitization - Implement WAF rules as additional layer - Security regression tests Comments: - @tech_lead_mike: Stop all other work, this is P0 - @sarah_dev: PR-578 ready with fixes for all 4 vulnerable endpoints - @alex_devops: Deployed hotfix to production 2025-09-19 at 14:30 UTC - @security_team_alice: Verified fix, conducting full pentest next week Resolution: All vulnerable endpoints patched. Added pre-commit hooks to catch raw SQL queries. Security training scheduled for team.",
  "url": "https://internal-git.techcorp.com/issues/1889",
  "type": "issue",
  "status": "closed",
  "priority": "critical",
  "assignee": "sarah_dev",
  "created_date": "2025-09-18",
  "resolved_date": "2025-09-19",
  "labels": "security, vulnerability, bug, sql",
  "related_pr": "PR-578"
}

ChatGPT는 정보를 종합하여 명확하게 제시합니다.

비하인드 스토리

프롬프트: 'ISSUE-1889의 세부 정보를 가져와'

1. ChatGPT 호출 fetch(“ISSUE-1889”)
2. Elasticsearch가 전체 문서를 검색합니다.
3. 모든 필드가 루트 수준에 포함된 전체 문서를 반환합니다.
4. ChatGPT는 정보를 종합하고 적절한 출처를 제시하며 응답합니다.

결론

이 문서에서는 전용 검색 및 가져오기 MCP 도구를 사용하여 ChatGPT를 Elasticsearch에 연결하고, 비공개 데이터에 대한 자연어 쿼리를 가능하게 하는 사용자 정의 MCP 서버를 구축했습니다.

이 MCP 패턴은 자연어로 쿼리하려는 모든 Elasticsearch 인덱스, 문서, 제품, 로그 또는 기타 데이터에 적용할 수 있습니다.

에이전트 RAG 소개

검색 증강 생성(RAG)은 LLM 기반 애플리케이션의 초석이 되어 모델이 사용자 쿼리를 기반으로 관련 컨텍스트를 검색하여 최적의 답변을 제공할 수 있게 해줍니다. RAG 시스템은 사전 학습된 LLM 지식에 국한되지 않고 API 또는 데이터 저장소의 외부 정보를 활용하여 LLM 응답의 정확성과 컨텍스트를 향상시킵니다. 반면에 AI 에이전트는 자율적으로 작동하여 지정된 목표를 달성하기 위해 의사 결정을 내리고 조치를 취합니다.

에이전트 RAG는 검색 증강 생성과 에이전트 추론의 강점을 통합한 프레임워크입니다. RAG를 상담원의 의사 결정 프로세스에 통합하여 시스템이 동적으로 데이터 소스를 선택하고, 더 나은 컨텍스트 검색을 위해 쿼리를 구체화하고, 더 정확한 응답을 생성하고, 피드백 루프를 적용하여 출력 품질을 지속적으로 개선할 수 있도록 지원합니다.

에이전트 RAG의 주요 기능

에이전트 RAG 프레임워크는 기존 RAG 시스템보다 크게 발전한 것입니다. 고정된 검색 프로세스를 따르는 대신 실시간으로 결과를 계획, 실행 및 최적화할 수 있는 동적 에이전트를 활용합니다.

에이전트 RAG 파이프라인을 구별하는 몇 가지 주요 기능을 살펴보겠습니다:

• 동적 의사 결정: 에이전트 RAG는 추론 메커니즘을 사용하여 사용자의 의도를 파악하고 각 쿼리를 가장 관련성이 높은 데이터 소스로 라우팅하여 정확하고 맥락에 맞는 응답을 생성합니다.
• 종합적인 쿼리 분석: 에이전틱 RAG는 하위 질문과 전반적인 의도를 포함하여 사용자 쿼리를 심층적으로 분석합니다. 쿼리 복잡성을 평가하고 가장 관련성이 높은 데이터 소스를 동적으로 선택하여 정보를 검색함으로써 정확하고 완전한 응답을 보장합니다.
• 다단계 협업: 이 프레임워크는 전문 에이전트 네트워크를 통해 다단계 협업을 가능하게 합니다. 각 에이전트는 더 큰 목표의 특정 부분을 처리하며, 일관된 결과를 달성하기 위해 순차적으로 또는 동시에 작업합니다.
• 자체 평가 메커니즘: 에이전트 RAG 파이프라인은 자체 반영을 사용하여 검색된 문서와 생성된 응답을 평가합니다. 검색된 정보가 쿼리에 완전히 부합하는지 확인한 다음 출력물의 정확성, 완전성, 사실적 일관성을 검토할 수 있습니다.
• 외부 도구와의 통합: 이 워크플로는 외부 API, 데이터베이스 및 실시간 정보 소스와 상호 작용하여 최신 정보를 통합하고 진화하는 데이터에 동적으로 적응할 수 있습니다.

에이전트 RAG의 워크플로 패턴

워크플로 패턴은 에이전트 AI가 안정적이고 효율적인 방식으로 LLM 기반 애플리케이션을 구성, 관리 및 오케스트레이션하는 방법을 정의합니다. 이러한 에이전트 워크플로우를 구현하기 위해 LangChain, LangGraph, CrewAI, LlamaIndex와 같은 여러 프레임워크와 플랫폼을 사용할 수 있습니다.

1. 순차적 검색 체인: 순차적 워크플로는 복잡한 작업을 단순하고 정돈된 단계로 나눕니다. 각 단계는 다음 단계의 입력을 개선하여 더 나은 결과로 이어집니다. 예를 들어 고객 프로필을 만들 때 한 상담원이 CRM에서 기본 세부 정보를 가져오고, 다른 상담원이 거래 데이터베이스에서 구매 내역을 검색한 다음, 최종 상담원이 이 정보를 결합하여 추천 또는 보고서를 위한 완전한 프로필을 생성할 수 있습니다.
2. 라우팅 검색 체인: 이 워크플로 패턴에서는 라우터 에이전트가 입력을 분석하여 가장 적합한 프로세스나 데이터 소스로 라우팅합니다. 이 접근 방식은 겹치는 부분이 최소화된 여러 데이터 원본이 존재하는 경우에 특히 효과적입니다. 예를 들어 고객 서비스 시스템에서 라우터 상담원은 기술 문제, 환불, 불만 등 들어오는 요청을 분류한 후 해당 부서로 라우팅하여 효율적으로 처리합니다.
3. 병렬 검색 체인: 이 워크플로 패턴에서는 여러 개의 독립적인 하위 작업이 동시에 실행되고 나중에 그 결과물을 집계하여 최종 응답을 생성합니다. 이 접근 방식은 처리 시간을 크게 단축하고 워크플로 효율성을 높입니다. 예를 들어 고객 서비스 병렬 워크플로우에서 한 상담원은 유사한 과거 요청을 검색하고 다른 상담원은 관련 지식창고 문서를 참조합니다. 그런 다음 애그리게이터는 이러한 출력을 결합하여 종합적인 해상도를 생성합니다.
4. 오케스트레이터 워커 체인: 이 워크플로는 독립적인 하위 작업을 활용한다는 점에서 병렬화와 유사점을 공유합니다. 그러나 중요한 차이점은 오케스트레이터 에이전트의 통합에 있습니다. 이 에이전트는 사용자 쿼리를 분석하여 런타임 중에 하위 작업으로 동적으로 분류하고 정확한 응답을 작성하는 데 필요한 적절한 프로세스 또는 도구를 식별하는 역할을 담당합니다.

에이전트 RAG 파이프라인을 처음부터 구축하기

에이전트 RAG의 원리를 설명하기 위해 LangChain과 Elasticsearch를 사용해 워크플로우를 설계해 보겠습니다. 이 워크플로에서는 여러 상담원이 협업하여 쿼리를 분석하고 관련 정보를 검색하며 결과를 평가하고 일관된 응답을 생성하는 라우팅 기반 아키텍처를 채택하고 있습니다. 이 Jupyter 노트북을 참조하여 이 예제를 따라할 수 있습니다.

워크플로는 라우터 에이전트가 사용자의 쿼리를 분석하여 최적의 검색 방법, 즉 vectorstore, websearch, composite 중 하나를 선택하는 것으로 시작됩니다. 벡터스토어는 기존의 RAG 기반 문서 검색을 처리하고, 웹검색은 벡터스토어에 저장되지 않은 최신 정보를 가져오며, 여러 소스의 정보가 필요한 경우 이 두 가지를 결합하는 복합적인 접근 방식을 사용합니다.

문서가 적합하다고 판단되면 요약 에이전트가 명확하고 문맥에 맞는 답변을 생성합니다. 그러나 문서가 불충분하거나 관련성이 없는 경우 쿼리 재작성 에이전트가 검색을 개선하기 위해 쿼리를 다시 작성합니다. 그러면 수정된 쿼리가 라우팅 프로세스를 다시 시작하여 시스템이 검색을 개선하고 최종 결과를 향상시킬 수 있습니다.

필수 구성 요소

이 워크플로에서는 예제를 효과적으로 실행하기 위해 다음과 같은 핵심 구성 요소를 사용합니다:

• Python 3.10
• 주피터 노트북
• Azure OpenAI
• Elasticsearch
• LangChain

계속 진행하기 전에 이 예제에 필요한 다음 환경 변수 집합을 구성하라는 메시지가 표시됩니다.

AZURE_OPENAI_ENDPOINT="Add your azure openai endpoint"
AZURE_OPENAI_KEY="Add your azure openai key"
AZURE_OPENAI_DEPLOYMENT="gpt-4.1"
AZURE_OPENAI_API_VERSION="Add your azure openai api version"

ES_ENDPOINT = "Add your Elasticsearch ENDPOINT"
ES_API_KEY = "Add your Elasticsearch API KEY"

데이터 소스

이 워크플로는 AG 뉴스 데이터 세트의 하위 집합을 사용하여 설명합니다. 이 데이터 세트는 국제, 스포츠, 비즈니스, 과학/기술 등 다양한 카테고리의 뉴스 기사로 구성되어 있습니다.

dataset = load_dataset("ag_news", split="train[:1000]")
docs = [
    Document(
        page_content=sample["text"],
        metadata={"category": sample["label"]}
    )
    for sample in dataset
]

ElasticsearchStore 모듈은 langchain_elasticsearch 에서 벡터 저장소로 활용됩니다. 검색을 위해 Elastic의 독점적인 임베딩 모델인 ELSER를 사용하는 SparseVectorStrategy를 구현합니다. 벡터 저장소를 시작하기 전에 ELSER 모델이 Elasticsearch 환경에 올바르게 설치 및 배포되었는지 확인해야 합니다.

elastic_vectorstore = ElasticsearchStore.from_documents(
    docs,
    es_url=ES_ENDPOINT,
    es_api_key=ES_API_KEY,
    index_name=index_name,
    strategy=SparseVectorStrategy(model_id=".elser_model_2"),
)

elastic_vectorstore.client.indices.refresh(index=index_name)

웹 검색 기능은 LangChain 커뮤니티 도구의 DuckDuckGoSearchRun을 사용하여 구현되어 시스템이 웹에서 실시간 정보를 효율적으로 검색할 수 있습니다. 보다 관련성 높은 결과를 제공할 수 있는 다른 검색 API를 사용하는 것도 고려해 볼 수 있습니다. 이 도구는 API 키 없이도 검색이 가능하기 때문에 선택되었습니다.

duckduckgo = DuckDuckGoSearchRun(description= "A custom DuckDuckGo search tool for finding latest news stories.", verbose=True)
def websearch_retriever(query):
    results = duckduckgo.run(f"{query}")
    return results

복합 검색기는 여러 소스를 조합해야 하는 쿼리를 위해 설계되었습니다. 웹에서 실시간 데이터를 검색하는 동시에 벡터 스토어에서 과거 뉴스를 참조하여 포괄적이고 맥락에 맞는 정확한 응답을 제공하는 데 사용됩니다.

def composite_retriever(query):
    related_docs = vectorstore_retriever(query)
    related_docs += websearch_retriever(query)
    return related_docs

상담원 설정하기

다음 단계에서는 이 워크플로 내에서 추론 및 의사 결정 기능을 제공하도록 LLM 에이전트를 정의합니다. 우리가 만들 LLM 체인에는 다음이 포함됩니다: router_chain, grade_docs_chain, rewrite_query_chain, 그리고 summary_chain.

라우터 에이전트는 LLM 어시스턴트를 사용하여 런타임에 주어진 쿼리에 가장 적합한 데이터 소스를 결정합니다. 채점 에이전트는 검색된 문서의 관련성을 평가합니다. 문서가 관련성이 있다고 판단되면 요약 에이전트로 전달되어 요약을 생성합니다. 그렇지 않으면 쿼리 재작성 에이전트가 쿼리를 재구성하여 라우팅 프로세스로 다시 보내 다른 검색을 시도합니다. 노트북의 LLM 체인 섹션에서 모든 에이전트에 대한 지침을 찾을 수 있습니다.

class RouteQuery(BaseModel):
    datasource: Literal["vectorstore", "websearch", "composite"] = Field(
        ...,
        description="Choose to route the query to web search, vectorstore or composite."
    )

router_prompt = ChatPromptTemplate.from_template("""You are an assistant that decides the best data source for questions based on news articles.
Choose one of the following options:
- 'vectorstore': for general, background, or historical news articles.
- 'websearch': for recent discoveries, 'latest', 'current', or '2025' type queries.
- 'composite': when the question needs both historical and current knowledge on news articles.

Question: {query}

Return one word: 'vectorstore', 'websearch', or 'composite'.
""")
router_structured = llm.with_structured_output(RouteQuery)
router_chain: RunnableSequence = router_prompt | router_structured

llm.with_structured_output 은 모델의 출력이 RouteQuery 클래스의 BaseModel에 정의된 사전 정의된 스키마를 따르도록 제한하여 결과의 일관성을 보장합니다. 두 번째 줄은 router_prompt 과 router_structured 을 연결하여 RunnableSequence 을 구성하여 입력 프롬프트가 언어 모델에 의해 처리되어 구조화된 스키마 준수 결과를 생성하는 파이프라인을 형성합니다.

그래프 노드 정의

이 부분에는 시스템의 여러 구성 요소 간에 흐르는 데이터를 나타내는 그래프의 상태를 정의하는 작업이 포함됩니다. 이러한 상태를 명확하게 지정하면 워크플로우의 각 노드가 어떤 정보에 액세스하고 업데이트할 수 있는지 알 수 있습니다.

class RAGState(TypedDict):
    query: str
    docs: List[Document]
    router: str
    summary: str
    self_reflection: bool
    retry_count: int = 0

상태가 정의되면 다음 단계는 그래프의 노드를 정의하는 것입니다. 노드는 데이터에 대한 특정 연산을 수행하는 그래프의 기능 단위와 같습니다. 파이프라인에는 7개의 서로 다른 노드가 있습니다.

def router(state: RAGState):
   router = router_chain.invoke({'query': state["query"]})
   logger.info(f"Router selected the datasource: {router.datasource}")
   logger.info(f"User query: {state['query']}")
   return {"router": router.datasource}

def vectorstore(state: RAGState):
   return {"docs": vectorstore_retriever(state["query"])}

def websearch(state: RAGState):
   return {"docs": websearch_retriever(state["query"])}

def composite(state: RAGState):
   return {"docs": composite_retriever(state["query"])}

def self_reflection(state: RAGState):
   evaluation = grade_docs_chain.invoke(
       {"query": state["query"], "docs": state["docs"]}
   )
   if evaluation.binary_score:
       logger.info(f"Self-reflection passed -- binary_score={evaluation.binary_score}")
   else:
       logger.info(f"Self-reflection failed -- binary_score={evaluation.binary_score}")

   return {
       "self_reflection": evaluation.binary_score,
   }

def query_rewriter(state: RAGState):
   retry_count = state.get("retry_count", 0) + 1
   new_query = rewrite_query_chain.invoke({"query": state["query"]})
   logger.info(f"Query rewritten: {new_query}, retry_count: {retry_count}")
   return {
       "query": new_query,
       "retry_count": retry_count,
   }

def summarize(state: RAGState):
   summary = summarize_chain.run(
       query=state["query"],
       docs=state["docs"],
   )
   return {"summary": summary}

query_rewriter 노드는 워크플로에서 두 가지 용도로 사용됩니다. 먼저, 자체 반영 에이전트가 평가한 문서가 불충분하거나 관련성이 없다고 판단되는 경우 검색을 개선하기 위해 rewrite_query_chain 을 사용하여 사용자 쿼리를 재작성합니다. 둘째, 쿼리가 재작성된 횟수를 추적하는 카운터 역할을 합니다.

노드가 호출될 때마다 워크플로 상태에 저장된 retry_count 이 증가합니다. 이 메커니즘은 워크플로우가 무한 루프에 빠지는 것을 방지합니다. retry_count 이 사전 정의된 임계값을 초과하면 시스템은 오류 상태, 기본 응답 또는 사용자가 선택한 기타 사전 정의된 조건으로 폴백할 수 있습니다.

그래프 컴파일하기

마지막 단계는 그래프의 가장자리를 정의하고 필요한 조건을 추가한 후 컴파일하는 것입니다. 모든 그래프는 워크플로우의 시작점 역할을 하는 지정된 시작 노드에서 시작해야 합니다. 그래프의 에지는 노드 간의 데이터 흐름을 나타내며 두 가지 유형이 있을 수 있습니다:

• 직선 가장자리: 한 노드에서 다른 노드로의 직접적이고 무조건적인 흐름을 정의합니다. 첫 번째 노드가 작업을 완료할 때마다 워크플로는 직선을 따라 다음 노드로 자동 진행됩니다.
• 조건부 에지: 현재 상태 또는 노드의 계산 결과에 따라 워크플로를 분기할 수 있습니다. 다음 노드는 평가 결과, 라우팅 결정 또는 재시도 횟수 등의 조건에 따라 동적으로 선택됩니다.

graph.add_edge(START, "router")

def after_router(state: RAGState):
   route = state.get("router", None)
   if route == "vectorstore":
       return "vectorstore"
   elif route == "websearch":
       return "websearch"
   else:
       return "composite"

def after_self_reflection(state: RAGState):
   if state["self_reflection"]:
           return "summarize"
   return "query_rewriter"

def after_query_rewriter(state: RAGState):
   while state['retry_count'] <= 3:
           return "router"
   raise RuntimeError("Maximum retries (3) reached -- evaluation failed.")

graph.add_conditional_edges(
   "router",
   after_router,
   {
       "vectorstore": "vectorstore",
       "websearch": "websearch",
       "composite": "composite"
   }
)

graph.add_edge("vectorstore", "self_reflection")
graph.add_edge("websearch", "self_reflection")
graph.add_edge("composite", "self_reflection")
graph.add_conditional_edges(
   "self_reflection",
   after_self_reflection,
   {
       "summarize": "summarize",
       "query_rewriter": "query_rewriter"
   }
)
graph.add_conditional_edges("query_rewriter", after_query_rewriter, {"router": "router"})
graph.add_edge("summarize", END)
agent=graph.compile()

이제 첫 번째 에이전트 RAG 파이프라인이 준비되었으며 컴파일된 에이전트를 사용하여 테스트할 수 있습니다.

result = agent.invoke({"query": query1})
logger.info(f"\nFinal Summary:\n: {result['summary']}")

에이전트 RAG 파이프라인 테스트

이제 아래와 같이 세 가지 유형의 쿼리를 사용하여 이 파이프라인을 테스트해 보겠습니다. 결과는 다를 수 있으며, 아래 예시는 한 가지 가능한 결과를 보여주는 것일 뿐입니다.

query1="What are the latest AI models released this month?"
query2="What technological innovations are discussed in Sci/Tech news?"
query3="Compare a Sci/Tech article from the dataset with a current web article about AI trends."

첫 번째 쿼리의 경우 라우터는 websearch 을 데이터 소스로 선택합니다. 쿼리가 자체 반영 평가에 실패하면 출력에 표시된 것처럼 쿼리 재작성 단계로 리디렉션됩니다.

INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: What are the latest AI models released this month?
Latest Singapore news, including the city state's relationships with Malaysia and Mahathir, China and Xi Jinping, and the rest of Southeast Asia. 3 days ago · The latest military news, insights and analysis from China. All the latest news, opinions and analysis on Hong Kong, China, Asia and around the world Latest news, in-depth features and opinion on Malaysia, covering politics, economy, society and the Asean member-nation's relationships with China, Singapore, and other Southeast Asian ... Oct 12, 2025 · Brics (an acronym for Brazil, Russia, India, China and South Africa) refers to an association of 10 leading emerging markets. The other member states are Egypt, Ethiopia, ...
INFO     | __main__:self_reflection:31 - Self-reflection failed -- binary_score=False
INFO     | __main__:query_rewriter:40 - Query rewritten: query='Which AI models have been officially released in June 2024?', retry_count: 1
INFO     | __main__:router:11 - Router selected the datasource: websearch
INFO     | __main__:router:12 - User query: query='Which AI models have been officially released in June 2024?'
Dream Machine is a text-to-video model created by Luma Labs and launched in June 2024 . It generates video output based on user prompts or still images. Dream Machine has been noted for its ability to realistically capture motion... Released in June 2023. In June 2024 , Baidu announced Ernie 4.0 Turbo. In April 2025, Ernie 4.5 Turbo and X1 Turbo were released . These models are optimized for faster response times and lower operational costs.[28][29]. The meaning of QUERY is question, inquiry. How to use query in a sentence. Synonym Discussion of Query. QUERY definition: 1. a question, often expressing doubt about something or looking for an answer from an authority.... Learn more. Query definition: a question; an inquiry.. See examples of QUERY used in a sentence.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: In June 2024, two AI models were officially released: Dream Machine, a text-to-video model launched by Luma Labs, and Ernie 4.0 Turbo, announced by Baidu, which is optimized for faster response times and lower operational costs.

다음으로 두 번째 쿼리를 통해 vectorstore 검색이 사용되는 예시를 살펴봅니다.

INFO     | __main__:router:11 - Router selected the datasource: vectorstore
INFO     | __main__:router:12 - User query: What technological innovations are discussed in Sci/Tech news?
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: Recent Sci/Tech news highlights several technological innovations: NASA is collaborating with Silicon Valley firms to build a powerful Linux-based supercomputer to support theoretical research and shuttle engineering; new chromatin transfer techniques have enabled the cloning of cats; cybersecurity advancements are being discussed in relation to protecting personal technology; Princeton University scientists assert that existing technologies can be used immediately to stabilize global warming; and a set of GameBoy micro-games has been recognized for innovation in game design.

최종 쿼리는 벡터스토어와 웹 검색을 모두 활용하는 복합 검색으로 진행됩니다.

INFO     | __main__:router:11 - Router selected the datasource: composite
INFO     | __main__:router:12 - User query: Compare a Sci/Tech article from the dataset with a current web article about AI trends.
Atlas currently only available on macOS, built on Chromium with planned features like ad-blocking still in development. OpenAI's Atlas browser launched with bold promises of AI -powered web browsing, but early real-world testing reveals a different story. Career-long data are updated to end-of-2024 and single recent year data pertain to citations received during calendar year 2024. The selection is based on the top 100,000 scientists by c-score (with and without self-citations) or a percentile rank of 2% or above in the sub-field. In this article I list 45 AI tools across 21 different categories. After exploring all the available options in each category, I've carefully selected the best tools based on my personal experience. Reading a complex technical article ? Simply highlight confusing terminology and ask "what's this?" to receive instant explanations. compare browsers. Comparison showing traditional browser navigation versus OpenAI Atlas AI -powered workflows. After putting Gemini, ChatGPT, Grok, and DeepSeek through rigorous testing in October 2025, it's clear that there isn't one AI that reigns supreme across all categories.
INFO     | __main__:self_reflection:29 - Self-reflection passed -- binary_score=True
INFO     | __main__::2 - 
Final Summary:
: A Sci/Tech article from the dataset highlights NASA's development of robust artificial intelligence software for planetary rovers, aiming to make them more self-reliant and capable of decision-making during missions. In contrast, a current web article about AI trends focuses on the proliferation of AI-powered tools across various categories, including browsers like OpenAI Atlas, and compares leading models such as Gemini, ChatGPT, Grok, and DeepSeek, noting that no single AI currently excels in all areas. While the NASA article emphasizes specialized AI applications for autonomous robotics in space exploration, the current trends article showcases the broadening impact of AI across consumer and professional technologies, with ongoing competition and rapid innovation among major AI platforms.

위의 워크플로우에서 에이전트 RAG는 사용자 쿼리에 대한 정보를 검색할 때 사용할 데이터 소스를 지능적으로 결정하여 응답의 정확성과 관련성을 개선합니다. 에이전트를 테스트하기 위해 추가 예제를 만들고 출력을 검토하여 흥미로운 결과가 나오는지 확인할 수 있습니다.

에이전트 RAG 워크플로우 구축을 위한 모범 사례

이제 에이전트 RAG의 작동 방식을 이해했으니 이러한 워크플로를 구축하기 위한 몇 가지 모범 사례를 살펴보겠습니다. 이 가이드라인을 따르면 시스템을 효율적이고 쉽게 유지 관리하는 데 도움이 됩니다.

• 폴백에 대비하세요: 워크플로우의 어느 단계에서든 장애가 발생할 경우를 대비하여 미리 대체 전략을 계획하세요. 여기에는 기본 답변 반환, 오류 상태 트리거 또는 대체 도구 사용이 포함될 수 있습니다. 이렇게 하면 시스템이 전체 워크플로우를 중단하지 않고도 장애를 원활하게 처리할 수 있습니다.
• 포괄적인 로깅을 구현하세요: 재시도, 생성된 출력, 라우팅 선택, 쿼리 재작성 등 워크플로우의 각 단계에서 로깅을 구현해 보세요. 이러한 로그는 투명성을 개선하고 디버깅을 더 쉽게 하며 시간이 지남에 따라 프롬프트, 상담원 행동 및 검색 전략을 개선하는 데 도움이 됩니다.
• 적절한 워크플로 패턴을 선택합니다: 사용 사례를 검토하여 필요에 가장 적합한 워크플로 패턴을 선택하세요. 단계별 추론에는 순차적 워크플로를, 독립적인 데이터 소스에는 병렬 워크플로를, 다중 도구 또는 복잡한 쿼리에는 오케스트레이터-작업자 패턴을 사용합니다.
• 평가 전략을 통합하세요: 워크플로우의 여러 단계에 평가 메커니즘을 통합하세요. 여기에는 자기 반성 에이전트, 검색된 문서 채점, 자동화된 품질 검사 등이 포함될 수 있습니다. 평가는 검색된 문서가 관련성이 있는지, 답변이 정확한지, 복잡한 쿼리의 모든 부분이 해결되었는지 확인하는 데 도움이 됩니다.

도전 과제

에이전트 RAG 시스템은 적응성, 정확성, 동적 추론 측면에서 상당한 이점을 제공하지만, 설계 및 구현 단계에서 해결해야 하는 특정 과제를 안고 있기도 합니다. 주요 과제 중 일부는 다음과 같습니다:

• 복잡한 워크플로: 더 많은 상담원과 의사 결정 포인트가 추가됨에 따라 전체 워크플로우가 점점 더 복잡해집니다. 이로 인해 런타임에 오류나 장애가 발생할 가능성이 높아질 수 있습니다. 가능하면 중복 상담원과 불필요한 의사 결정 지점을 제거하여 워크플로우를 간소화하는 데 우선순위를 두세요.
• 확장성: 대규모 데이터 세트와 많은 쿼리 양을 처리하기 위해 에이전트 RAG 시스템을 확장하는 것은 어려울 수 있습니다. 효율적인 인덱싱, 캐싱 및 분산 처리 전략을 통합하여 규모에 맞게 성능을 유지하세요.
• 오케스트레이션 및 컴퓨팅 오버헤드: 여러 에이전트가 포함된 워크플로를 실행하려면 고급 오케스트레이션이 필요합니다. 여기에는 병목 현상과 충돌을 방지하기 위한 신중한 스케줄링, 종속성 관리, 상담원 조정이 포함되며, 이 모든 것이 전반적인 시스템 복잡성을 가중시킵니다.
• 평가의 복잡성: 각 단계마다 고유한 평가 전략이 필요하기 때문에 이러한 워크플로를 평가하는 데는 고유한 어려움이 있습니다. 예를 들어 RAG 단계에서는 검색된 문서의 관련성과 완전성을 평가해야 하며, 생성된 요약의 품질과 정확성을 확인해야 합니다. 마찬가지로 쿼리 재구성의 효과는 재작성된 쿼리가 검색 결과를 개선하는지 여부를 판단하기 위한 별도의 평가 로직이 필요합니다.

결론

이 블로그 게시물에서는 에이전트 RAG의 개념을 소개하고 에이전트 AI의 자율 기능을 통합하여 기존 RAG 프레임워크를 개선하는 방법을 강조했습니다. 에이전트 RAG의 핵심 기능을 살펴보고 실제 예제를 통해 이러한 기능을 시연했으며, Elasticsearch를 벡터 저장소로 사용하고 LangChain을 에이전트 프레임워크를 생성하는 뉴스 어시스턴트를 구축했습니다.

또한 에이전트 RAG 파이프라인을 설계하고 구현할 때 고려해야 할 모범 사례와 주요 과제에 대해서도 논의했습니다. 이러한 인사이트는 개발자가 검색, 추론 및 의사 결정을 효과적으로 결합하는 강력하고 확장 가능하며 효율적인 에이전트 시스템을 만드는 데 도움을 주기 위한 것입니다.

그럼 이제 무엇을 해야 할까요?

우리가 구축한 워크플로우는 단순하여 개선과 실험을 위한 충분한 여지를 남겨두고 있습니다. 다양한 임베딩 모델을 실험하고 검색 전략을 개선하여 이를 개선할 수 있습니다. 또한 검색된 문서의 우선 순위를 다시 지정하는 에이전트를 통합하면 도움이 될 수 있습니다. 또 다른 탐색 영역은 에이전트 프레임워크에 대한 평가 전략을 개발하는 것으로, 특히 다양한 유형의 프레임워크에 적용 가능한 공통적이고 재사용 가능한 접근 방식을 식별하는 것입니다. 마지막으로, 더 크고 복잡한 데이터 세트에서 이러한 프레임워크를 실험해 보세요.

그동안 비슷한 실험을 해보신 경험이 있으시다면 공유해 주시면 감사하겠습니다! 커뮤니티 Slack 채널이나 토론 포럼을 통해 자유롭게 피드백을 제공하거나 소통하세요.

리소스

• Self-RAG: 자기 성찰을 통한 검색, 생성 및 비평 학습하기
• 에이전트 검색-증강 세대: 에이전트 RAG에 대한 설문 조사

점수 범위 문제

하이브리드 검색이 어려운 주요 이유 중 하나인 다양한 점수 범위를 살펴보기 위해 무대를 설정해 보겠습니다. 우리의 오랜 친구 BM25는 무한한 점수를 만들어냅니다. 즉, BM25는 0에 가까운 점수부터 (이론적으로) 무한대까지 다양한 점수를 생성할 수 있습니다. 반대로 dense_vector 필드에 대한 쿼리는 0과 1 사이의 점수를 생성합니다. 이 문제를 더욱 악화시키는 semantic_text 은 임베딩을 색인하는 데 사용되는 필드 유형을 난독화하므로 색인 및 추론 엔드포인트 구성에 대한 자세한 지식이 없으면 쿼리의 점수 범위를 알기 어려울 수 있습니다. 이는 어휘 검색 결과와 의미 검색 결과를 통합하려고 할 때 문제가 되는데, 의미 검색 결과가 더 관련성이 높더라도 어휘 검색 결과가 의미 검색 결과보다 우선할 수 있기 때문입니다. 이 문제에 대한 일반적인 해결책은 결과를 인터리빙하기 전에 점수를 정규화하는 것입니다. 이를 위한 두 가지 도구, 선형 검색기와 RRF 검색기가 있습니다.

RRF 검색기는 문서 순위를 관련성 측정값으로 사용하고 점수를 버리는 RRF 알고리즘을 적용합니다. 점수는 고려되지 않으므로 점수 범위 불일치는 문제가 되지 않습니다.

리니어 리트리버는 선형 조합을 사용하여 문서의 최종 점수를 결정합니다. 여기에는 문서에 대한 각 구성 요소 쿼리의 점수를 가져와서 정규화한 다음 합산하여 총 점수를 생성하는 작업이 포함됩니다. 수학적으로 이 연산은 다음과 같이 표현할 수 있습니다:

Total Score = 𝚺(N(Sx))

여기서 N 은 정규화 함수이고 SX 는 쿼리 X 의 점수입니다. 정규화 함수는 각 쿼리의 점수를 동일한 범위를 사용하도록 변환하기 때문에 여기서 핵심적인 역할을 합니다. 리니어 리트리버에 대해 자세히 알아보려면 여기를 참조하세요.

분석하기

사용자는 이러한 도구를 사용하여 효과적인 하이브리드 검색을 구현할 수 있지만 색인에 대한 약간의 지식이 필요합니다. 두 개의 필드가 있는 인덱스를 쿼리하는 리니어 리트리버의 예를 살펴보겠습니다:

PUT linear_retriever_example
{
  "mappings": {
    "properties": {
      "semantic_text_field": { <1>
        "type": "semantic_text",
        "inference_id": ".multilingual-e5-small-elasticsearch"
      },
      "text_field": { <2>
        "type": "text"
      }
    }
  }
}

1. semantic_text_field 는 텍스트 임베딩 모델인 E5를 사용하는 semantic_text 필드입니다.

text_field 는 표준 text 필드입니다.

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "match": { <1>
                  "semantic_text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

1. semantic_text 필드에서 match 쿼리를 사용하며, Elasticsearch 8.18/9.0에서 지원이 추가되었습니다.

쿼리를 구성할 때 semantic_text_field 은 텍스트 임베딩 모델을 사용하므로 이 쿼리에 대한 모든 쿼리는 0에서 1 사이의 점수를 생성한다는 점을 염두에 두어야 합니다. 또한 text_field 은 표준 text 필드이므로 이 필드로 쿼리하면 무제한 점수가 생성된다는 점도 알아야 합니다. 적절한 연관성을 가진 결과 집합을 만들려면 쿼리 점수를 결합하기 전에 정규화하는 리트리버를 사용해야 합니다. 이 예에서는 각 쿼리의 점수를 0과 1 사이의 값으로 정규화하는 minmax 정규화와 함께 선형 검색기를 사용합니다.

이 예제의 쿼리 구성은 두 개의 필드만 관련되어 있기 때문에 매우 간단합니다. 그러나 더 많은 필드와 다양한 유형이 추가되면 매우 빠르게 복잡해질 수 있습니다. 이는 효과적인 하이브리드 검색 쿼리를 작성하려면 쿼리 대상 인덱스에 대한 심층적인 지식이 필요한 경우가 많으므로 구성 요소 쿼리 점수를 조합하기 전에 적절하게 정규화해야 한다는 것을 보여줍니다. 이는 하이브리드 검색의 광범위한 채택을 가로막는 장벽이 됩니다.

쿼리 그룹화

예제를 확장해 보겠습니다: 하나의 text 필드와 두 개의 semantic_text 필드를 쿼리하려면 어떻게 해야 할까요? 다음과 같이 쿼리를 작성할 수 있습니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_1",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "semantic": {
                  "field": "semantic_text_field_2",
                  "query": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

겉으로 보기에는 좋아 보이지만 잠재적인 문제가 있습니다. 이제 semantic_text 필드 매치가 전체 점수의 ⅔를 차지합니다:

Total Score = N(semantic_text_field_1 score) + N(semantic_text_field_2 score) + N(text_field score)

이는 불균형한 점수를 만들기 때문에 원하지 않을 수도 있습니다. 필드가 3개만 있는 이 예제에서는 그 영향이 눈에 띄지 않을 수 있지만, 더 많은 필드가 쿼리되면 문제가 됩니다. 예를 들어, 대부분의 인덱스에는 시맨틱 필드보다 훨씬 더 많은 어휘 필드가 포함되어 있습니다(예 dense_vector, sparse_vector, 또는 semantic_text). 위의 패턴을 사용하여 어휘 필드 9개와 의미 필드 1개가 있는 인덱스를 쿼리한다면 어떨까요? 어휘 일치 항목이 점수의 90% 을 차지하여 의미론적 검색의 효과를 무색하게 만들었습니다.

이 문제를 해결하는 일반적인 방법은 쿼리를 어휘 및 의미 범주로 그룹화하고 두 범주에 균등하게 가중치를 부여하는 것입니다. 이렇게 하면 어느 한 카테고리가 총점을 지배하는 것을 방지할 수 있습니다.

이를 실천에 옮겨 보겠습니다. 이 예제에서 리니어 리트리버를 사용할 때 그룹화된 쿼리 접근 방식은 어떤 모습일까요?

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "retrievers": [
        {
          "retriever": {
            "linear": {
              "retrievers": [
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_1",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                },
                {
                  "retriever": {
                    "standard": {
                      "query": {
                        "semantic": {
                          "field": "semantic_text_field_2",
                          "query": "foo"
                        }
                      }
                    }
                  },
                  "normalizer": "minmax"
                }
              ]
            }
          },
          "normalizer": "minmax"
        },
        {
          "retriever": {
            "standard": {
              "query": {
                "match": {
                  "text_field": "foo"
                }
              }
            }
          },
          "normalizer": "minmax"
        }
      ]
    }
  }
}

와, 점점 장황해지네요! 전체 쿼리를 살펴보기 위해 위아래로 여러 번 스크롤해야 했을 수도 있습니다! 여기서는 두 가지 수준의 정규화를 사용하여 쿼리 그룹을 생성합니다. 수학적으로는 다음과 같이 표현할 수 있습니다:

Total Score = N(N(semantic_text_field_1 score) + N(semantic_text_field_2 score)) + N(text_field score)

이 두 번째 정규화 수준은 semantic_text 필드와 text 필드에 대한 쿼리의 가중치가 균등하게 적용되도록 합니다. 이 예제에서는 어휘 필드가 하나뿐이므로 text_field 에 대한 두 번째 수준 정규화를 생략하여 더 자세한 설명을 생략했습니다.

이 쿼리 구조는 이미 다루기 힘든데다 세 개의 필드만 쿼리하고 있습니다. 더 많은 필드를 쿼리할수록 숙련된 검색 실무자라도 관리하기가 점점 더 어려워집니다.

다중 필드 쿼리 형식

이 모든 것을 간소화하기 위해 Elasticsearch 8.19, 9.1 및 서버리스에서 선형 및 RRF 검색기에 대한 다중 필드 쿼리 형식을 추가했습니다. 이제 위와 동일한 쿼리를 수행할 수 있습니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

쿼리가 55줄에서 단 9줄로 줄어듭니다! Elasticsearch는 인덱스 매핑을 자동으로 사용합니다:

• 쿼리되는 각 필드의 유형을 결정합니다.
• 각 필드를 어휘 또는 의미론적 범주로 그룹화합니다.
• 최종 점수에서 각 카테고리에 균등하게 가중치를 부여합니다.

이를 통해 누구나 인덱스나 사용된 추론 엔드포인트에 대한 세부 정보를 몰라도 효과적인 하이브리드 검색 쿼리를 실행할 수 있습니다.

RRF를 사용하는 경우 순위가 관련성의 프록시로 사용되므로 normalizer 을 생략할 수 있습니다:

GET rrf_retriever_example/_search
{
  "retriever": {
    "rrf": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field" ],
      "query": "foo"
    }
  }
}

필드별 부스팅

리니어 리트리버를 사용할 때 필드별 부스트를 적용하여 특정 필드에서 경기의 중요도를 조정할 수 있습니다. 예를 들어 semantic_text 필드 2개와 text 필드 2개 등 4개의 필드를 쿼리한다고 가정해 보겠습니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1", "semantic_text_field_2", "text_field_1", "text_field_2" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

기본적으로 각 필드는 해당 그룹(어휘 또는 의미)에서 동일하게 가중치가 부여됩니다. 점수 분석은 다음과 같습니다:

즉, 각 필드는 총 점수의 25% %입니다.

field^boost 구문을 사용하여 모든 필드에 필드별 부스트를 추가할 수 있습니다. semantic_text_field_1 와 text_field_1 에 2의 부스트를 적용해 보겠습니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_1^2", "semantic_text_field_2", "text_field_1^2", "text_field_2" ]
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

이제 점수 분석은 다음과 같습니다:

각 쿼리 그룹은 여전히 동일하게 가중치가 적용되지만 이제 그룹 내 필드 가중치가 변경되었습니다:

• semantic_text_field_1 시맨틱 쿼리 그룹 점수는 66%, 총 점수는 33% 입니다.
• text_field_1 는 어휘 쿼리 그룹 점수 66%, 총 점수 33% 입니다.

와일드카드 해상도

fields 매개변수에 * 와일드카드를 사용하여 여러 필드를 일치시킬 수 있습니다. 위의 예를 계속 이어서, 이 쿼리는 기능적으로emantic_text_field_1, semantic_text_field_2, text_field_1 을 명시적으로 쿼리하는 것과 동일합니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "fields": [ "semantic_text_field_*", "*_field_1" ],
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

*_field_1 패턴이 text_field_1 및 semantic_text_field_1 와 모두 일치한다는 점이 흥미롭습니다. 이는 자동으로 처리되며, 각 필드가 명시적으로 쿼리된 것처럼 쿼리가 실행됩니다. semantic_text_field_1 이 두 패턴과 모두 일치해도 괜찮습니다. 모든 필드 이름 일치 항목은 쿼리 실행 전에 중복이 제거됩니다.

와일드카드는 다양한 방법으로 사용할 수 있습니다:

• 접두사 일치(예: *_text_field)
• 인라인 매칭(예: semantic_*_field)
• 접미사 일치(예: semantic_text_field_*)

*_text_field_* 와 같이 여러 와일드카드를 사용하여 위의 조합을 적용할 수도 있습니다.

기본 쿼리 필드

다중 필드 쿼리 형식을 사용하면 전혀 모르는 인덱스를 쿼리할 수도 있습니다. fields 매개변수를 생략하면 index.query.default_field 인덱스 설정으로 지정된 모든 필드를 쿼리합니다:

GET linear_retriever_example/_search
{
  "retriever": {
    "linear": {
      "query": "foo",
      "normalizer": "minmax"
    }
  }
}

기본적으로 index.query.default_field 은 * 으로 설정되어 있습니다. 이 와일드카드는 용어 쿼리를 지원하는 인덱스의 모든 필드 유형(대부분)으로 확인합니다. 예외는 있습니다:

• dense_vector 필드
• rank_vector 필드
• 지오메트리 필드: geo_point, shape

이 기능은 타사에서 제공하는 색인에 대해 하이브리드 검색 쿼리를 수행하려는 경우에 특히 유용합니다. 다중 필드 쿼리 형식을 사용하면 간단한 방법으로 적절한 쿼리를 실행할 수 있습니다. fields 매개변수만 제외하면 해당되는 모든 필드가 쿼리됩니다.

결론

점수 범위 문제로 인해 효과적인 하이브리드 검색을 구현하기가 어려울 수 있으며, 특히 쿼리되는 인덱스나 사용 중인 추론 엔드포인트에 대한 인사이트가 제한적인 경우 더욱 그렇습니다. 선형 및 RRF 검색기를 위한 다중 필드 쿼리 형식은 자동화된 쿼리 그룹화 기반의 하이브리드 검색 방식을 간단하고 접근하기 쉬운 API로 패키징하여 이러한 어려움을 덜어줍니다. 필드별 부스팅, 와일드카드 해상도 및 기본 쿼리 필드와 같은 추가 기능을 통해 다양한 사용 사례를 포괄하는 기능을 확장할 수 있습니다.

지금 바로 다중 필드 쿼리 형식을 사용해 보세요.

무료 체험 판으로 완전 관리형 Elasticsearch 서버리스 프로젝트에서 다중 필드 쿼리 형식의 선형 및 RRF 검색기를 확인해 보세요. 8.19 & 9.1부터 스택 버전으로도 사용할 수 있습니다.

명령 한 번으로 로컬 환경에서 몇 분 안에 시작할 수 있습니다:

curl -fsSL https://elastic.co/start-local | sh

이 문서에서는 GPT-OSS와 Elastic 에이전트 빌더를 사용해 HR용 AI 에이전트를 구축하는 방법을 설명합니다. 상담원은 OpenAI, Anthropic 또는 외부 서비스에 데이터를 보내지 않고도 질문에 답변할 수 있습니다.

LM Studio를 사용하여 GPT-OSS를 로컬로 서비스하고 이를 Elastic Agent Builder에 연결합니다.

이 글을 마치면 정보와 모델을 완벽하게 제어하면서 직원 데이터에 대한 자연어 질문에 답할 수 있는 맞춤형 AI 에이전트를 보유하게 됩니다.

필수 구성 요소

이 문서에는 다음이 필요합니다:

• Elastic Cloud 호스팅 9.2, 서버리스 또는 로컬 배포
• 32GB RAM이 장착된 머신 권장(GPT-OSS 20B의 경우 최소 16GB)
• LM Studio 설치
• 도커 데스크톱 설치

GPT-OSS를 사용하는 이유는 무엇인가요?

로컬 LLM을 사용하면 자체 인프라에 배포하고 필요에 맞게 미세 조정할 수 있습니다. 이 모든 기능을 사용하면서 모델과 공유하는 데이터를 제어할 수 있으며, 물론 외부 제공업체에 라이선스 비용을 지불할 필요가 없습니다.

OpenAI는 개방형 모델 생태계를 위한 노력의 일환으로 2025년 8월 5일에 GPT-OSS를 출시했습니다.

20B 매개변수 모델은 다음을 제공합니다:

• 도구 사용 기능
• 효율적인 추론
• OpenAI SDK 호환
• 에이전트 워크플로와 호환

벤치마크 비교:

솔루션 아키텍처

아키텍처는 전적으로 로컬 컴퓨터에서 실행됩니다. Elastic(Docker에서 실행)은 LM Studio를 통해 로컬 LLM과 직접 통신하며, Elastic 에이전트 빌더는 이 연결을 사용하여 직원 데이터를 쿼리할 수 있는 사용자 정의 AI 에이전트를 생성합니다.

자세한 내용은 이 문서를 참조하세요.

HR용 AI 에이전트 구축: 단계

구현을 5단계로 나눠서 설명하겠습니다:

1. 로컬 모델로 LM 스튜디오 구성
2. Docker로 로컬 Elastic 배포
3. Elastic에서 OpenAI 커넥터 생성
4. Elasticsearch에 직원 데이터 업로드
5. AI 에이전트 빌드 및 테스트

1단계: GPT-OSS 20B로 LM Studio 구성하기

LM Studio는 컴퓨터에서 로컬로 대규모 언어 모델을 실행할 수 있는 사용자 친화적인 애플리케이션입니다. OpenAI 호환 API 서버를 제공하므로 복잡한 설정 과정 없이 Elastic과 같은 도구와 쉽게 통합할 수 있습니다. 자세한 내용은 LM Studio 문서를 참조하세요.

먼저 공식 웹사이트에서 LM Studio를 다운로드하여 설치합니다. 설치가 완료되면 애플리케이션을 엽니다.

LM Studio 인터페이스에서:

1. 검색 탭으로 이동하여 "GPT-OSS"를 검색합니다.
2. OpenAI에서 openai/gpt-oss-20b
3. 다운로드를 클릭하세요.

이 모델의 크기는 약 12.10GB입니다. 인터넷 연결 상태에 따라 다운로드하는 데 몇 분 정도 걸릴 수 있습니다.

모델이 다운로드되면

1. 로컬 서버 탭으로 이동합니다.
2. OPENAI/GPT-OSS-20B를 선택합니다.
3. 기본 포트 1234 사용
4. 오른쪽 패널에서 로드로 이동하여 컨텍스트 길이를 40K 이상으로 설정합니다.

5. 서버 시작을 클릭합니다.

서버가 실행 중이면 이 메시지가 표시되어야 합니다.

[LM STUDIO SERVER] Success! HTTP server listening on port 1234
[LM STUDIO SERVER] Supported endpoints:
[LM STUDIO SERVER] ->	GET  http://localhost:1234/v1/models
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/responses
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/chat/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/completions
[LM STUDIO SERVER] ->	POST http://localhost:1234/v1/embeddings
Server started.

2단계: Docker로 로컬 Elastic 배포하기

이제 Docker를 사용해 로컬에서 Elasticsearch와 Kibana를 설정하겠습니다. Elastic은 전체 설정 프로세스를 처리하는 편리한 스크립트를 제공합니다. 자세한 내용은 공식 문서를 참조하세요.

시작-로컬 스크립트 실행

터미널에서 다음 명령을 실행합니다:

curl -fsSL https://elastic.co/start-local | sh

이 스크립트는

• Elasticsearch와 Kibana 다운로드 및 구성하기
• Docker Compose를 사용하여 두 서비스 모두 시작
• 30일 플래티넘 평가판 라이선스 자동 활성화

예상 출력

다음 메시지가 표시될 때까지 기다렸다가 표시된 비밀번호와 API 키를 저장하세요. Kibana에 액세스하려면 이 키가 필요합니다:

🎉 Congrats, Elasticsearch and Kibana are installed and running in Docker!
🌐 Open your browser at http://localhost:5601
   Username: elastic
   Password: KSUlOMNr
🔌 Elasticsearch API endpoint: http://localhost:9200
🔑 API key: cnJGX0pwb0JhOG00cmNJVklUNXg6cnNJdXZWMnM4bncwMllpQlFlUTlWdw==
Learn more at https://github.com/elastic/start-local

Kibana에 액세스

브라우저를 열고 다음으로 이동합니다:

http://localhost:5601

터미널 출력에서 얻은 자격 증명을 사용하여 로그인합니다.

상담원 빌더 사용

Kibana에 로그인한 후, 관리 > AI > 에이전트 빌더로 이동하여 에이전트 빌더를 활성화합니다.

3단계: Elastic에서 OpenAI 커넥터 만들기

이제 로컬 LLM을 사용하도록 Elastic을 구성하겠습니다.

액세스 커넥터

1. Kibana에서
2. 프로젝트 설정으로 이동 > 관리
3. 알림 및 인사이트에서 커넥터를선택합니다.
4. 커넥터 만들기를 클릭합니다.

커넥터 구성

커넥터 목록에서 OpenAI를 선택합니다. LM Studio는 OpenAI SDK를 사용하므로 호환성이 뛰어납니다.

이 값으로 필드를 채웁니다:

• 커넥터 이름: LM Studio - GPT-OSS 20B
• OpenAI 제공업체를 선택합니다: 기타(OpenAI 호환 서비스)
• URL: http://host.docker.internal:1234/v1/chat/completions
• 기본 모델: OPENAI/GPT-OSS-20B
• API 키: testkey-123(LM Studio 서버는 인증이 필요하지 않으므로 어떤 텍스트도 작동합니다.)

구성을 완료하려면 저장 & 테스트를 클릭합니다.

중요: 상담원 빌더가 제대로 작동하려면 '네이티브 함수 호출 사용'을 켜야 합니다. 이 기능을 활성화하지 않으면 No tool calls found in the response 오류가 발생합니다.

연결 테스트

Elastic은 자동으로 연결을 테스트합니다. 모든 것이 올바르게 구성되면 다음과 같은 성공 메시지가 표시됩니다:

대응:

{
  "status": "ok",
  "data": {
    "id": "chatcmpl-flj9h0hy4wcx4bfson00an",
    "object": "chat.completion",
    "created": 1761189456,
    "model": "openai/gpt-oss-20b",
    "choices": [
      {
        "index": 0,
        "message": {
          "role": "assistant",
          "content": "Hello! 👋 How can I assist you today?",
          "reasoning": "Just greet.",
          "tool_calls": []
        },
        "logprobs": null,
        "finish_reason": "stop"
      }
    ],
    "usage": {
      "prompt_tokens": 69,
      "completion_tokens": 23,
      "total_tokens": 92
    },
    "stats": {},
    "system_fingerprint": "openai/gpt-oss-20b"
  },
  "actionId": "ee1c3aaf-bad0-4ada-8149-118f52dad757"
}

4단계: 직원 데이터를 Elasticsearch에 업로드하기

이제 HR 직원 데이터 세트를 업로드하여 상담원이 민감한 데이터로 어떻게 작업하는지 보여드리겠습니다. 이 구조로 가상의 데이터 집합을 생성했습니다.

데이터 세트 구조

{
  "employee_id": "0f4dce68-2a09-4cb1-b2af-6bcb4821539b",
  "full_name": "Daffi Stiebler",
  "email": "lscutchings0@huffingtonpost.com",
  "date_of_birth": "1975-06-20T15:39:36Z",
  "hire_date": "2025-07-28T00:10:45Z",
  "job_title": "Physical Therapy Assistant",
  "department": "HR",
  "salary": "108455",
  "performance_rating": "Needs Improvement",
  "years_of_experience": 2,
  "skills": "Java",
  "education_level": "Master's Degree",
  "manager": "Carl MacGibbon",
  "emergency_contact": "Leigha Scutchings",
  "home_address": "5571 6th Park"
}

매핑으로 인덱스 만들기

먼저 적절한 매핑으로 인덱스를 생성합니다. 일부 주요 필드에 semantic_text 필드를 사용하여 인덱스에 시맨틱 검색 기능을 사용할 수 있습니다.

​​PUT hr-employees
{
  "mappings": {
    "properties": {
      "@timestamp": {
        "type": "date"
      },
      "employee_id": {
        "type": "keyword"
      },
      "full_name": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "email": {
        "type": "keyword"
      },
      "date_of_birth": {
        "type": "date",
        "format": "iso8601"
      },
      "hire_date": {
        "type": "date",
        "format": "iso8601"
      },
      "job_title": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "department": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "salary": {
        "type": "double"
      },
      "performance_rating": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "years_of_experience": {
        "type": "long"
      },
      "skills": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "education_level": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "manager": {
        "type": "text",
        "copy_to": "employee_semantic"
      },
      "emergency_contact": {
        "type": "keyword"
      },
      "home_address": {
        "type": "keyword"
      },
      "employee_semantic": {
        "type": "semantic_text"
      }
    }
  }
}

대량 API로 색인 생성

데이터 세트를 복사하여 Kibana의 개발 도구에 붙여넣고 실행합니다:

POST hr-employees/_bulk
{"index": {}}
{"employee_id": "57728b91-e5d7-4fa8-954a-2384040d3886", "full_name": "Filide Gane", "email": "vhallahan1@booking.com", "job_title": "Business Systems Development Analyst", "department": "Marketing", "salary": "$52330.27", "performance_rating": "Meets Expectations", "years_of_experience": 12, "skills": "Java", "education_level": "Bachelor's Degree", "date_of_birth": "2000-02-07T16:49:32Z", "hire_date": "2023-11-07T13:03:16Z", "manager": "Freedman Kings", "emergency_contact": "Vilhelmina Hallahan", "home_address": "75 Dennis Junction"}
{"index": {}}
{"employee_id": "...", ...}

데이터 확인

쿼리를 실행하여 확인합니다:

GET hr-employees/_search

5단계: AI 에이전트 빌드 및 테스트

모든 구성이 완료되었으면 이제 Elastic 에이전트 빌더를 사용해 사용자 정의 AI 에이전트를 빌드할 차례입니다. 자세한 내용은 Elastic 설명서를 참조하세요.

커넥터 추가

새 에이전트를 생성하기 전에, 기본 커넥터가 Elastic Managed LLM이므로 LM Studio - GPT-OSS 20B 이라는 사용자 정의 커넥터를 사용하도록 에이전트 빌더를 설정해야 합니다. 이를 위해 프로젝트 설정 > 관리 > GenAI 설정으로 이동한 다음, 생성한 프로젝트를 선택하고 저장을 클릭합니다.

에이전트 빌더 액세스

1. 상담원으로이동
2. 새 상담원 만들기를클릭합니다.

상담원 구성하기

새 상담원을 만들 때 필수 필드는 상담원 ID, 표시 이름 및 표시 지침입니다.

하지만 시스템 프롬프트와 비슷하지만 사용자 지정 상담원을 위해 상담원이 어떻게 행동하고 툴과 상호 작용할지 안내하는 사용자 지정 지침과 같은 더 많은 사용자 지정 옵션이 있습니다. 레이블은 상담원, 아바타 색상 및 아바타 심볼을 정리하는 데 도움이 됩니다.

데이터 집합을 기반으로 상담원에게 선택한 것은

상담원 ID입니다: hr_assistant

사용자 지정 지침:

You are an HR Analytics Assistant that helps answer questions about employee data.
When responding to queries:
- Provide clear, concise answers
- Include relevant employee details (name, department, salary, skills)
- Format monetary values with currency symbols
- Be professional and maintain data confidentiality

레이블: Human Resources 및 GPT-OSS

표시 이름: HR Analytics Assistant

설명을 표시합니다:

A specialized AI assistant for Human Resources that helps analyze employee data, compensation, performance metrics, and talent management. Ask questions about employees, departments, salaries, or performance analytics.

여기에 모든 데이터가 있으면 새 상담원 저장을 클릭할 수 있습니다.

에이전트 테스트

이제 직원 데이터에 대해 자연어 질문을 하면 GPT-OSS 20B가 의도를 파악하고 적절한 답변을 생성합니다.

프롬프트:

Which employee is the one with the highest salary in the hr-employees index?

답변:

에이전트 프로세스였습니다:

1. GPT-OSS 커넥터를 사용하여 질문 이해하기

2. (기본 제공 도구 또는 사용자 정의 ES|QL을 사용하여) 적절한 Elasticsearch 쿼리를 생성합니다.

3. 일치하는 직원 기록 검색

4. 적절한 서식을 사용하여 자연어로 결과 표시

기존의 어휘 검색과 달리 GPT-OSS 기반 에이전트는 의도와 문맥을 이해하므로 정확한 필드 이름이나 쿼리 구문을 몰라도 정보를 쉽게 찾을 수 있습니다. 상담원의 사고 과정에 대한 자세한 내용은 이 문서를 참조하세요.

결론

이 문서에서는 Elastic의 에이전트 빌더를 사용해 로컬에서 실행 중인 OpenAI GPT-OSS 모델에 연결하기 위해 사용자 정의 AI 에이전트를 구축했습니다. 이 아키텍처는 로컬 머신에 Elastic과 LLM을 모두 배포함으로써 외부 서비스로 정보를 전송하지 않고도 데이터를 완벽하게 제어하면서 생성형 AI 기능을 활용할 수 있게 해줍니다.

실험으로 GPT-OSS 20B를 사용했지만, 공식적으로 Elastic 에이전트 빌더에 권장되는 모델은 여기를 참조하세요. 고급 추론 기능이 필요한 경우, 로컬에서 실행하려면 더 높은 사양의 컴퓨터가 필요하지만 복잡한 시나리오에서 더 나은 성능을 발휘하는 120B 매개변수 변형도 있습니다. 자세한 내용은 OpenAI 공식 문서를 참조하세요.

몇 주 전, 전 세계에서 2,000명 이상의 참가자가 모인 대규모 오프라인 해커톤 중 하나인 Cal Hacks 12.0을 후원할 수 있는 놀라운 기회를 가졌습니다. 서버리스에서 Elastic 에이전트 빌더를 가장 잘 활용할 수 있는 전용 상금 트랙을 제공했는데, 그 반응은 놀라웠습니다. 단 36시간 만에 산불 인텔리전스 도구 구축부터 StackOverflow 유효성 검사기까지 에이전트 빌더를 창의적인 방식으로 사용한 29개의 제출물이 접수되었습니다.

인상적인 프로젝트 외에도 Cal Hacks 12.0의 경험은 Stack을 처음 접하는 개발자들의 빠르고 여과 없는 피드백이라는 또 다른 가치 있는 것을 얻게 해 주었습니다. 해커톤은 촉박한 일정, 사전 정보 부족, 예측할 수 없는 장애물(악명 높은 와이파이 중단 등)이 있는 독특한 압박 테스트입니다. 이를 통해 개발자 환경의 장점과 개선이 필요한 부분을 정확히 파악할 수 있습니다. 개발자들이 점점 더 LLM 기반 워크플로우를 통해 새로운 방식으로 Elastic Stack과 상호 작용함에 따라 이는 이제 더욱 중요해졌습니다. 이 블로그 게시물에서는 참가자들이 에이전트 빌더로 구축한 내용과 그 과정에서 배운 점을 자세히 살펴봅니다.

수상 프로젝트

1등 에이전트 오버플로

스택 오버플로가 LLM 및 에이전트 시대에 맞게 재구축되었습니다.

여기에서 에이전트오버플로에 대해 자세히 알아보세요.

에이전트오버플로는 대부분의 AI 개발자가 직면하는 문제를 해결합니다: LLM이 환각을 일으키고, 채팅 기록이 사라지고, 개발자가 동일한 문제를 다시 해결하느라 시간을 낭비하는 등의 문제를 해결합니다.

에이전트오버플로는 실제 문제 해결 쌍을 캡처, 검증 및 재표출하여 개발자가 환각의 소용돌이를 끊고 더 빠르게 출시할 수 있도록 지원합니다.

작동 방식:

1. JSON - "솔루션 스키마" 공유.

Claude 공유에서 클릭 한 번으로 다음을 포함하는 구조화된 형식인 공유 솔루션 JSON을 스크랩, 추출 및 조립합니다:

• 문제
• 컨텍스트
• 코드
• 태그
• 검증된 솔루션 단계.

유효성 검사기(LAVA)가 구조를 검사하고 적용하면 사용자가 한 줄의 추가 컨텍스트를 추가하면 Elasticsearch 내에 저장되고 색인됩니다.

2. 솔루션 찾기

문제가 발생하면 Find Solution 을 클릭하면 AgentOverflow가 현재 대화를 스크랩하여 쿼리를 작성하고 이를 사용하여 하이브리드 Elasticsearch 검색을 실행하여 결과를 표시합니다:

• 순위가 매겨진 커뮤니티 검증 수정 사항
• 원래 문제를 해결한 정확한 안내 메시지

이를 통해 개발자는 현재 세션을 빠르게 복사, 붙여넣기, 차단 해제할 수 있습니다.

3. MCP - LLM을 위한 컨텍스트 주입

MCP(모델 컨텍스트 프로토콜)를 통해 Elasticsearch 내에 저장된 구조화된 솔루션에 연결하면 별도의 노이즈 없이 런타임에 높은 신호 컨텍스트(코드, 로그, 구성, 이전 수정 사항)를 LLM에 공급할 수 있습니다.

에이전트 오버플로에서는 에이전트 빌더와 Elasticsearch를 사용해 관련 컨텍스트를 LLM에 주입하는 구조화된 메모리 계층으로 사용합니다. 이를 통해 수동적인 챗봇에서 상황 인식 문제 해결사로 변신합니다.

준우승 MarketMind

6개의 Elastic 에이전트가 제공하는 시장 에너지에 대한 실시간 해석 가능한 보기.

마켓마인드에 대한 자세한 내용은 여기를 참조하세요.

MarketMind는 초보 트레이더에게 파편화된 시장 데이터를 명확한 실시간 신호로 변환하는 플랫폼을 제공함으로써 자리를 잡았습니다. 가격 움직임, 펀더멘털, 심리, 변동성을 여러 도구에 분산하는 대신 MarketMind는 이 모든 정보를 하나의 플랫폼에 통합하여 트레이더가 실행 가능한 인사이트를 얻을 수 있도록 도와줍니다. 이 프로젝트는 에이전트를 구축할 때 복잡한 ES|QL 쿼리를 사용하기도 했습니다.

작동 방식:

1. 실시간 시장 데이터 수집

MarketMind는 가격 움직임, 펀더멘털, 심리, 변동성, 위험 지표를 야후 파이낸스로부터 가져옵니다. 이 데이터는 수집되어 여러 개의 Elasticsearch 인덱스로 구성됩니다.

2. 6명의 전문 에이전트가 시장을 분석합니다.

에이전트 빌더로 구축된 각 에이전트는 시장의 다른 계층에 초점을 맞춥니다. 이들은 Elasticsearch 인덱스에서 읽고, 자체 도메인별 메트릭을 계산하고, 점수와 추론이 포함된 표준화된 JSON 출력을 생성합니다.

3. 통합된 '시장 에너지' 모델로 신호 통합

합산된 결과는 각 종목 주위에 빛나는 펄스로 표시되어 모멘텀이 형성되고 있는지, 리스크가 상승하고 있는지, 심리가 변화하고 있는지를 보여줍니다.

4. 인사이트 시각화

프론트엔드는 타입스크립트, SVG 물리 기반 비주얼, 라이브 캔들스틱 차트를 위한 Chart.js를 사용하여 React와 Next.js로 구축되었습니다. 이렇게 하면 원시 분석이 실시간으로 실행 가능한 피드백으로 전환됩니다.

기타 흥미로운 프로젝트:

다음은 스택의 여러 부분에서 Elastic을 사용한 다른 강력한 경쟁자들입니다:

여기에서 트랙에 제출된 프로젝트의 전체 목록을 확인하세요.

개발자로부터 배운 점

• 에이전트 빌더는 사용자 친화적입니다:

대부분의 팀은 이전에 Elastic을 사용해 본 적이 없었지만 적은 지원으로도 신속하게 에이전트를 구축할 수 있었습니다. 더 많은 안내가 필요한 분들을 위해 워크숍을 열었지만, 대부분 데이터를 수집하고 해당 데이터에 대한 작업을 수행하는 에이전트를 구축할 수 있었습니다.

• LLM은 kNN 쿼리에 탁월하지만 여전히 ES|QL 생성에 대한 지침이 필요합니다:

ChatGPT-5에 ES|QL 쿼리를 생성하도록 요청하면 ES|QL과 SQL이 혼합된 잘못된 정보가 반환되는 경우가 많았습니다. 마크다운 파일로 문서를 LLM에 공급하는 것은 실행 가능한 해결 방법인 것 같았습니다.

• 스냅샷 전용 ES|QL 함수가 문서로 유출되었습니다:

곧 출시될 FIRST 및 LAST 집계 함수는 의도치 않게 ES|QL 문서에 포함되었습니다. 이러한 문서를 ChatGPT에 제공했기 때문에 모델은 아직 서버리스에서 사용할 수 없는 기능임에도 불구하고 이러한 기능을 충실히 사용했습니다. 그룹의 피드백에 힘입어 엔지니어링 팀은 게시된 문서에서 기능을 제거하는 수정 사항을 신속하게 공개하고 병합했습니다(PR #137341).

• 서버리스 관련 안내가 누락되었습니다:

한 팀이 조회 모드로 생성되지 않은 인덱스에서 LOOKUP JOIN 을 활성화하려고 시도했습니다. 오류 메시지는 서버리스에 존재하지 않는 명령을 쫓는다는 메시지를 보냈습니다. 이 사실을 제품 팀에 전달했고, 제품 팀은 즉시 서버리스와 관련된 실행 가능한 메시지에 대한 수정 사항을 공개했습니다. 장기적으로는 재색인 복잡성을 완전히 숨기는 것이 비전입니다(이슈 #4838).

• 대면 이벤트의 가치:

온라인 해커톤도 훌륭하지만, 빌더와 어깨를 맞대고 디버깅할 때 얻을 수 있는 빠른 피드백을 따라올 수 있는 것은 없습니다. 다양한 사용 사례에서 에이전트 빌더를 통합하는 팀을 지켜보면서 ES|QL을 사용하는 개발자 경험을 개선할 수 있는 부분을 발견하고 비동기 채널을 통해 문제를 해결하는 것보다 훨씬 더 빠르게 문제를 해결했습니다.

결론

Cal Hacks 12.0은 주말 동안 멋진 데모를 보여줬을 뿐만 아니라 새로운 개발자들이 Elastic Stack과 어떻게 상호작용하는지에 대한 인사이트도 제공했습니다. 단 36시간 만에 팀들이 에이전트 빌더를 선택하고, Elasticsearch로 데이터를 수집하고, 멀티 에이전트 시스템을 설계하고, 다양한 방식으로 기능을 테스트하는 것을 보았습니다. 이번 행사를 통해 대면 이벤트가 중요한 이유를 다시 한 번 깨달았습니다. 빠른 피드백 루프, 실제 대화, 실습 디버깅을 통해 현재 개발자의 요구 사항을 파악하는 데 도움이 되었습니다. 저희가 배운 내용을 엔지니어링 팀에 다시 전달할 수 있게 되어 기쁩니다. 다음 해커톤에서 뵙겠습니다.

이 글은 동일한 에이전트 내에서 A2A와 MCP 아키텍처를 모두 구현하여 두 프레임워크의 고유한 이점을 제대로 활용할 수 있는 이점을 설명한 "Elasticsearch에서 A2A 프로토콜과 MCP를 사용하여 LLM 에이전트 뉴스룸 만들기!" 글의 후속 글입니다. 직접 데모를 실행하려는 경우 저장소를 사용할 수 있습니다.

뉴스룸 에이전트가 A2A와 MCP를 사용하여 뉴스 기사를 제작하기 위해 어떻게 협업하는지 살펴보겠습니다. 에이전트가 작동하는 모습을 볼 수 있는 리포지토리는 여기에서 확인할 수 있습니다.

1단계: 스토리 과제

뉴스 책임자 (클라이언트 역할)가 스토리를 할당합니다:

{
  "message_type": "task_request",
  "sender": "news_chief",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "assignment": {
      "topic": "Renewable Energy Adoption in Europe",
      "angle": "Policy changes driving solar and wind expansion",
      "target_length": 1200,
      "deadline": "2025-09-30T18:00:00Z"
    }
  }
}

2단계: 리포터가 리서치 요청

리포터 에이전트는 배경 정보가 필요하다는 것을 인식하고 A2A를 통해 리포터 에이전트에게 위임합니다:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "fact_gathering",
    "parameters": {
      "queries": [
        "EU renewable energy capacity 2024",
        "Solar installations growth Europe",
        "Wind energy policy changes 2024"
      ],
      "depth": "comprehensive"
    }
  }
}

3단계: 리포터가 아카이브 에이전트에게 기록 컨텍스트를 요청합니다.

리포터 에이전트는 역사적 맥락이 스토리를 강화할 수 있다는 것을 알고 있습니다. A2A를 통해 (Elastic의 A2A 에이전트로 구동되는) 아카이브 에이전트에 위임하여 뉴스룸의 Elasticsearch 기반 기사 아카이브를 검색합니다:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "archive_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "parent_task_id": "story_renewable_energy_2024",
    "capability": "search_archive",
    "parameters": {
      "query": "European renewable energy policy changes and adoption trends over past 5 years",
      "focus_areas": ["solar", "wind", "policy", "Germany", "France"],
      "time_range": "2019-2024",
      "result_count": 10
    }
  }
}

4단계: 아카이브 에이전트가 MCP와 함께 Elastic A2A 에이전트 사용

아카이브 에이전트는 Elastic의 A2A 에이전트를 사용하며, 이 에이전트는 다시 MCP를 사용해 Elasticsearch 도구에 액세스합니다. 이는 A2A가 에이전트 협업을 지원하는 동시에 MCP가 툴 액세스를 제공하는 하이브리드 아키텍처를 보여줍니다:

# Archive Agent using Elastic A2A Agent
async def search_historical_articles(self, query_params):
    # The Archive Agent sends a request to Elastic's A2A Agent
    elastic_response = await self.a2a_client.send_request(
        agent="elastic_agent",
        capability="search_and_analyze",
        parameters={
            "natural_language_query": query_params["query"],
            "index_pattern": "newsroom-articles-*",
            "filters": {
                "topics": query_params["focus_areas"],
                "date_range": query_params["time_range"]
            },
            "analysis_type": "trend_analysis"
        }
    )
    
    # Elastic's A2A Agent internally uses MCP tools:
    # - platform.core.search (to find relevant articles)
    # - platform.core.generate_esql (to analyze trends)
    # - platform.core.index_explorer (to identify relevant indices)
    
    return elastic_response

아카이브 에이전트는 Elastic의 A2A 에이전트로부터 포괄적인 기록 데이터를 받아 리포터에게 반환합니다:

{
  "message_type": "task_response",
  "sender": "archive_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "archive_search_renewable_2024",
    "status": "completed",
    "archive_data": {
      "historical_articles": [
        {
          "title": "Germany's Energiewende: Five Years of Solar Growth",
          "published": "2022-06-15",
          "key_points": [
            "Germany added 7 GW annually 2020-2022",
            "Policy subsidies drove 60% of growth"
          ],
          "relevance_score": 0.94
        },
        {
          "title": "France Balances Nuclear and Renewables",
          "published": "2023-03-20",
          "key_points": [
            "France increased renewable target to 40% by 2030",
            "Solar capacity doubled 2021-2023"
          ],
          "relevance_score": 0.89
        }
      ],
      "trend_analysis": {
        "coverage_frequency": "EU renewable stories increased 150% since 2019",
        "emerging_themes": ["policy incentives", "grid modernization", "battery storage"],
        "coverage_gaps": ["Small member states", "offshore wind permitting"]
      },
      "total_articles_found": 47,
      "search_confidence": 0.91
    }
  }
}

이 단계에서는 Elastic의 A2A 에이전트가 뉴스룸 워크플로우에 어떻게 통합되는지 보여드립니다. Archive 에이전트(뉴스룸 전용 에이전트)는 Elastic의 A2A 에이전트(타사 전문가)와 협력하여 Elasticsearch의 강력한 검색 및 분석 기능을 활용합니다. Elastic의 에이전트는 내부적으로 MCP를 사용하여 Elasticsearch 도구에 액세스하므로 에이전트 조정(A2A)과 도구 액세스(MCP)가 깔끔하게 분리되어 있습니다.

5단계: 연구자가 MCP 서버 사용

연구원 에이전트는 여러 MCP 서버에 액세스하여 정보를 수집합니다:

# Researcher Agent using MCP to access tools
async def gather_facts(self, queries):
    results = []
    
    # Use News API MCP Server
    news_data = await self.mcp_client.invoke_tool(
        server="news_api_mcp",
        tool="search_articles",
        parameters={
            "query": queries[0],
            "date_range": "2024-01-01 to 2024-09-30",
            "sources": ["reuters", "bloomberg", "euractiv"]
        }
    )
    
    # Use Statistics MCP Server
    stats_data = await self.mcp_client.invoke_tool(
        server="eurostat_mcp",
        tool="get_energy_statistics",
        parameters={
            "metrics": ["solar_capacity_mw", "wind_capacity_mw"],
            "countries": ["EU27"],
            "year": 2024
        }
    )
    
    # Use Fact-Checking MCP Server
    verified_facts = await self.mcp_client.invoke_tool(
        server="factcheck_mcp",
        tool="verify_claims",
        parameters={
            "claims": [
                "EU solar capacity increased 40% in 2024",
                "Germany leads in wind installations"
            ]
        }
    )
    
    return self._synthesize_research(news_data, stats_data, verified_facts)

6단계: 연구원이 리포터에게 데이터를 반환합니다.

리서처 에이전트는 A2A를 통해 종합적인 리서치를 다시 보냅니다:

{
  "message_type": "task_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "task_id": "research_eu_renewable_2024",
    "status": "completed",
    "research_data": {
      "key_facts": [
        {
          "claim": "EU solar capacity reached 260 GW in 2024",
          "source": "Eurostat Q3 2024 Report",
          "confidence": 0.95,
          "verified": true
        },
        {
          "claim": "Germany installed 12 GW of wind capacity in 2024",
          "source": "German Federal Network Agency",
          "confidence": 0.92,
          "verified": true
        }
      ],
      "statistics": {
        "solar_growth_rate": "35%",
        "wind_growth_rate": "28%"
      },
      "sources_count": 15
    }
  }
}

7단계: 기자가 기사 작성

리포터 에이전트는 리서치 데이터와 자체 LLM 기능을 사용하여 기사를 작성합니다. 글을 작성하는 동안 리포터는 스타일과 템플릿을 위해 MCP 서버를 사용합니다:

# Reporter Agent writing with MCP assistance
async def write_article(self, research_data, assignment):
    # Get style guidelines via MCP
    style_guide = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="style://editorial/ap_style_guide"
    )
    
    # Get article template via MCP
    template = await self.mcp_client.get_resource(
        server="newsroom_mcp",
        resource="template://articles/news_story"
    )
    
    # Generate article using LLM + research + style
    draft = await self.llm.generate(
        prompt=f"""
        Write a news article following these guidelines:
        {style_guide}
        
        Using this template:
        {template}
        
        Based on this research:
        {research_data}
        
        Assignment: {assignment}
        """
    )
    
    # Self-evaluate confidence in claims
    confidence_check = await self._evaluate_confidence(draft)
    
    return draft, confidence_check

8단계: 낮은 신뢰도로 인한 재조사 트리거

리포터 에이전트가 초안을 평가한 결과 한 클레임의 신뢰도가 낮다는 것을 발견했습니다. 연구원 에이전트에게 또 다른 요청을 보냅니다:

{
  "message_type": "collaboration_request",
  "sender": "reporter_agent",
  "receiver": "researcher_agent",
  "payload": {
    "request_type": "fact_verification",
    "claims": [
      {
        "text": "France's nuclear phase-down contributed to 15% increase in renewable capacity",
        "context": "Discussing policy drivers for renewable growth",
        "current_confidence": 0.45,
        "required_confidence": 0.80
      }
    ],
    "urgency": "high"
  }
}

연구원은 사실 확인 MCP 서버를 사용하여 클레임을 확인하고 업데이트된 정보를 반환합니다:

{
  "message_type": "collaboration_response",
  "sender": "researcher_agent",
  "receiver": "reporter_agent",
  "payload": {
    "verified_claims": [
      {
        "original_claim": "France's nuclear phase-down contributed to 15% increase...",
        "verified_claim": "France's renewable capacity increased 18% in 2024, partially offsetting reduced nuclear output",
        "confidence": 0.88,
        "corrections": "Percentage was 18%, not 15%; nuclear phase-down is gradual, not primary driver",
        "sources": ["RTE France", "French Energy Ministry Report 2024"]
      }
    ]
  }
}

9단계: 리포터가 수정하여 편집자에게 제출합니다.

리포터는 확인된 사실을 통합하고 A2A를 통해 완성된 초안을 편집 에이전트에게 보냅니다:

{
  "message_type": "task_request",
  "sender": "reporter_agent",
  "receiver": "editor_agent",
  "payload": {
    "task_id": "edit_renewable_story",
    "parent_task_id": "story_renewable_energy_2024",
    "content": {
      "headline": "Europe's Renewable Revolution: Solar and Wind Surge 30% in 2024",
      "body": "[Full article text...]",
      "word_count": 1185,
      "sources": [/* array of sources */]
    },
    "editing_requirements": {
      "check_style": true,
      "check_facts": true,
      "check_seo": true
    }
  }
}

10단계: MCP 도구를 사용한 편집자 리뷰

편집자 에이전트는 여러 MCP 서버를 사용하여 문서를 검토합니다:

# Editor Agent using MCP for quality checks
async def review_article(self, content):
    # Grammar and style check
    grammar_issues = await self.mcp_client.invoke_tool(
        server="grammarly_mcp",
        tool="check_document",
        parameters={"text": content["body"]}
    )
    
    # SEO optimization check
    seo_analysis = await self.mcp_client.invoke_tool(
        server="seo_mcp",
        tool="analyze_content",
        parameters={
            "headline": content["headline"],
            "body": content["body"],
            "target_keywords": ["renewable energy", "Europe", "solar", "wind"]
        }
    )
    
    # Plagiarism check
    originality = await self.mcp_client.invoke_tool(
        server="plagiarism_mcp",
        tool="check_originality",
        parameters={"text": content["body"]}
    )
    
    # Generate editorial feedback
    feedback = await self._generate_feedback(
        grammar_issues, 
        seo_analysis, 
        originality
    )
    
    return feedback

편집자가 글을 승인하고 앞으로 보냅니다:

{
  "message_type": "task_response",
  "sender": "editor_agent",
  "receiver": "reporter_agent",
  "payload": {
    "status": "approved",
    "quality_score": 9.2,
    "minor_edits": [
      "Changed 'surge' to 'increased' in paragraph 3 for AP style consistency",
      "Added Oxford comma in list of countries"
    ],
    "approved_content": "[Final edited article]"
  }
}

11단계: CI/CD를 통해 게시자 게시

마지막으로 프린터 에이전트는 CMS 및 CI/CD 파이프라인을 위한 MCP 서버를 사용하여 승인된 문서를 게시합니다:

# Publisher Agent publishing via MCP
async def publish_article(self, content, metadata):
    # Upload to CMS via MCP
    cms_result = await self.mcp_client.invoke_tool(
        server="wordpress_mcp",
        tool="create_post",
        parameters={
            "title": content["headline"],
            "body": content["body"],
            "status": "draft",
            "categories": metadata["categories"],
            "tags": metadata["tags"],
            "featured_image_url": metadata["image_url"]
        }
    )
    
    post_id = cms_result["post_id"]
    
    # Trigger CI/CD deployment via MCP
    deploy_result = await self.mcp_client.invoke_tool(
        server="cicd_mcp",
        tool="trigger_deployment",
        parameters={
            "pipeline": "publish_article",
            "environment": "production",
            "post_id": post_id,
            "schedule": "immediate"
        }
    )
    
    # Track analytics
    await self.mcp_client.invoke_tool(
        server="analytics_mcp",
        tool="register_publication",
        parameters={
            "post_id": post_id,
            "publish_time": datetime.now().isoformat(),
            "story_id": metadata["story_id"]
        }
    )
    
    return {
        "status": "published",
        "post_id": post_id,
        "url": f"https://newsroom.example.com/articles/{post_id}",
        "deployment_id": deploy_result["deployment_id"]
    }

게시자는 A2A를 통해 게시를 확인합니다:

{
  "message_type": "task_complete",
  "sender": "printer_agent",
  "receiver": "news_chief",
  "payload": {
    "task_id": "story_renewable_energy_2024",
    "status": "published",
    "publication": {
      "url": "https://newsroom.example.com/articles/renewable-europe-2024",
      "published_at": "2025-09-30T17:45:00Z",
      "post_id": "12345"
    },
    "workflow_metrics": {
      "total_time_minutes": 45,
      "agents_involved": ["reporter", "researcher", "archive", "editor", "printer"],
      "iterations": 2,
      "mcp_calls": 12
    }
  }
}

다음은 위에서 설명한 것과 동일한 에이전트를 사용하여 첨부된 리포지토리에 있는 A2A 워크플로우의 전체 시퀀스입니다.

결론

A2A와 MCP는 모두 최신 증강-LLM 인프라 패러다임에서 중요한 역할을 담당하고 있습니다. A2A는 복잡한 멀티 에이전트 시스템을 위한 유연성을 제공하지만 잠재적으로 휴대성이 떨어지고 운영 복잡성이 높아질 수 있습니다. MCP는 멀티에이전트 오케스트레이션을 처리하도록 설계되지는 않았지만 구현 및 유지 관리가 더 간편한 도구 통합을 위한 표준화된 접근 방식을 제공합니다.

선택은 이분법적이지 않습니다. 뉴스룸의 예시를 통해 알 수 있듯이, 가장 정교하고 효과적인 LLM 지원 시스템은 에이전트가 A2A 프로토콜을 통해 조정하고 전문화하면서 MCP 서버를 통해 도구와 리소스에 액세스하는 두 가지 접근 방식을 결합하는 경우가 많습니다. 이 하이브리드 아키텍처는 MCP의 표준화 및 에코시스템의 장점과 함께 멀티 에이전트 시스템의 조직적 이점을 제공합니다. 이는 선택의 여지가 전혀 없을 수도 있음을 시사합니다. 두 가지를 모두 표준 접근 방식으로 사용하기만 하면 됩니다.

특정 사용 사례에 적합한 결과를 만들기 위해 두 솔루션을 가장 잘 조합하여 테스트하고 결정하는 것은 개발자 또는 아키텍트의 몫입니다. 각 접근 방식의 강점, 한계, 적절한 적용 사례를 이해하면 보다 효과적이고 유지 관리가 용이하며 확장 가능한 AI 시스템을 구축할 수 있습니다.

디지털 뉴스룸, 고객 서비스 플랫폼, 리서치 어시스턴트 또는 기타 LLM 기반 애플리케이션을 구축하는 경우, 조정 요구 사항(A2A)과 도구 액세스 요구 사항(MCP)을 신중하게 고려하면 성공의 길로 들어설 수 있습니다.

추가 리소스

• Elasticsearch 에이전트 빌더: https://www.elastic.co/docs/solutions/search/elastic-agent-builder
• A2A 사양: https://a2a-protocol.org/latest/specification/
• A2A 및 MCP 통합: https://a2a-protocol.org/latest/topics/a2a-and-mcp/
• 모델 컨텍스트 프로토콜: https://modelcontextprotocol.io

검색은 죽지 않았고, 단지 이동했을 뿐입니다.

따라서 주로 텍스트 상자를 통해 문맥을 검색하고 반환된 정보(문맥)를 사용하여 직접 답변을 구성하는 방식에서 이제는 자연어를 사용하여 상담원에게 원하는 것을 말하면 자동으로 검색하여 답변을 작성하는 방식으로 전환했습니다. 기술 업계의 많은 사람들이 이러한 변화를 지적하며 "검색은 죽었다"고 선언하고 있지만(물론 SEO와 애드워즈 세계는 확실히 변화하고 있습니다 . 누구세요?) 검색은 여전히 에이전트 운영에 절대적으로 중요하며, 지금은 대부분 도구를 통해 보이지 않는 곳에서 수행될 뿐입니다.

이전에는 사용자가 주관적인 관련성의 주요 중재자였습니다. 사용자마다 검색을 실행하는 이유가 다르고, 개인적인 경험에 따라 결과의 상대적 정확도가 달라집니다. 에이전트가 우리와 동일한(또는 더 나은) 결론에 도달할 수 있다고 믿으려면 에이전트가 액세스할 수 있는 컨텍스트 정보가 우리의 주관적인 의도에 최대한 가깝도록 보장해야 합니다. 우리는 그 목표를 향해 LLM을 제공하는 맥락을 설계해야 합니다!

하이브리드 검색 검색을 통한 컨텍스트 생성

1부에서 다시 한 번 말씀드리지만, Elastic의 하이브리드 검색은 기존 키워드 기반 검색의 강점(구문 유연성, 키워드 정밀도, 관련성 점수)과 벡터 유사성 검색의 의미론적 이해를 결합하고 다양한 재순위 지정 기술을 제공합니다. 이 시너지 효과(이 단어의 진정한 용도는 찾아볼 수 없습니다!) 를 사용하면 콘텐츠를 타겟팅하는 방식에 훨씬 더 미묘한 차이가 있는 쿼리를 통해 연관성이 높은 결과를 얻을 수 있습니다. 검색 단계 중 하나로 주관적 연관성을 적용할 수 있다는 것뿐만 아니라, 실제로는 1단계 검색에 다른 모든 모드와 함께 연관성 점수를 한 번에 포함할 수 있다는 것입니다.

뛰어난 정확도 & 효율성

분산 검색, 검색 및 순위 재지정을 제공할 수 있는 데이터 플랫폼을 기본 컨텍스트 검색 엔진으로 사용하는 것은 매우 합리적입니다. 고급 쿼리 구문을 사용하여 주관적 의도의 누락된 구성 요소를 추가하고, 반환된 문맥 정보의 가치를 흐리게 하거나 방해할 수 있는 콘텐츠를 필터링할 수 있습니다. 사용 가능한 개별 구문 옵션 중에서 선택하거나 각 유형의 데이터를 가장 잘 이해하는 방식으로 타겟팅하는 단일 검색으로 모달리티를 결합한 다음 순위를 재조정하여 결합/재배열할 수 있습니다. 원하는 필드/값만 포함하도록 응답을 필터링하여 불필요한 데이터를 차단할 수 있습니다. 상담원 서비스에서는 이러한 타겟팅 유연성을 통해 컨텍스트를 검색하는 방식이 매우 정확한 툴을 구축할 수 있습니다.

컨텍스트 세분화(집계 및 비콘텐츠 신호)

집계는 도구가 컨텍스트 창에 제공하는 콘텐츠를 구성하는 데 특히 유용할 수 있습니다. 집계는 자연스럽게 반환된 컨텍스트 데이터의 형태에 대한 수치 기반 사실을 제공하므로, LLM이 더 쉽고 정확하게 추론할 수 있습니다. 집계는 계층적으로 중첩될 수 있기 때문에 LLM에 다단계 세부 정보를 쉽게 추가하여 보다 미묘한 차이를 파악할 수 있습니다. 집계는 컨텍스트 창 크기를 관리하는 데도 도움이 됩니다. 10만 개의 문서에 대한 쿼리 결과를 수백 개의 집계된 인사이트 토큰으로 쉽게 줄일 수 있습니다.

비콘텐츠 신호는 인기도, 신선도, 지리적 위치, 카테고리, 호스트 다양성, 가격대 등 결과의 추가적인 특성을 나타내는 데이터의 내재적 지표로, 현재 보고 있는 내용에 대한 더 큰 그림을 알려줍니다. 이러한 정보는 상담원이 수신한 컨텍스트의 중요도를 평가하는 데 유용할 수 있습니다. 몇 가지 간단한 예시를 통해 이를 가장 잘 설명할 수 있습니다:

• 최근에 게시된 인기 콘텐츠 강화하기 - 문서에 대한 지식창고가 있다고 가정해 보세요. 사용자의 검색어와 관련된 문서를 찾고 싶지만, 최근 문서이면서 다른 사용자가 도움이 되었다고 판단한 문서(예: "좋아요" 수가 많은 문서)도 부스팅하고 싶을 수 있습니다. 이 시나리오에서는 하이브리드 검색을 사용하여 관련성 있는 문서를 찾은 다음 게시 날짜와 인기도를 조합하여 순위를 재조정할 수 있습니다.
• 판매 및 재고 조정 기능이 있는 전자상거래 검색 - 전자상거래 환경에서는 고객에게 검색어와 일치하는 제품을 표시하는 동시에 잘 팔리고 재고가 있는 제품을 홍보하고 싶을 수 있습니다. 또한 재고가 적은 제품의 순위를 낮춰 고객의 불만을 피할 수도 있습니다.
• 버그 트래커에서 심각도가 높은 이슈 우선 순위 지정하기 - 소프트웨어 개발팀의 경우 이슈를 검색할 때 심각도가 높고 우선 순위가 높으며 최근에 업데이트된 이슈를 먼저 표시하는 것이 중요합니다. '중요도' 및 '가장 많이 논의된' 등의 비신호를 사용하여 다양한 요소를 독립적으로 평가하여 가장 중요하고 활발하게 논의된 이슈가 맨 위에 표시되도록 할 수 있습니다.

이러한 예제 쿼리 등은 함께 제공되는 Elasticsearch Labs 콘텐츠 페이지에서 확인할 수 있습니다.

보안 시행

컨텍스트 엔지니어링을 위해 Elastic과 같은 검색 기반 속도 계층을 활용할 때의 중요한 장점은 기본 제공 보안 프레임워크입니다. Elastic의 플랫폼은 세분화된 역할 기반 액세스 제어(RBAC)와 속성 기반 액세스 제어(ABAC)를 통해 에이전트 및 생성 AI 작업에 제공되는 컨텍스트가 민감한 개인 보유 정보를 존중하고 보호하도록 보장합니다. 즉, 쿼리가 효율적으로 처리될 뿐만 아니라 요청을 시작한 상담원이나 사용자의 특정 권한에 따라 결과가 필터링됩니다.

에이전트는 인증된 사용자로 실행되므로 플랫폼에 내장된 보안 기능을 통해 보안이 암시적으로 적용됩니다:

• 세분화된 권한: 문서, 필드 또는 용어 수준에서 액세스 권한을 정의하여 AI 에이전트가 볼 권한이 있는 데이터만 받도록 하세요.
• 역할 기반 액세스 제어(RBAC): 에이전트 또는 사용자에게 역할을 할당하여 정의된 책임에 따라 특정 데이터 세트 또는 기능에 대한 액세스 권한을 부여합니다.
• 속성 기반 액세스 제어(ABAC): 데이터, 사용자 또는 환경의 속성을 기반으로 동적 액세스 정책을 구현하여 고도로 적응력이 뛰어나고 상황에 맞는 보안을 구현할 수 있습니다.
• 문서 수준 보안(DLS) 및 필드 수준 보안(FLS): 이러한 기능은 검색된 문서 내에서도 승인된 부분만 볼 수 있도록 하여 민감한 정보가 노출되는 것을 방지합니다.
• 엔터프라이즈 보안과 통합: 기존 ID 관리 시스템(예: LDAP, SAML, OIDC)과 원활하게 통합하여 조직 전체에 일관된 보안 정책을 적용할 수 있습니다.

이러한 보안 조치를 컨텍스트 검색 메커니즘에 직접 통합함으로써 Elastic은 보안 게이트키퍼 역할을 수행하여 AI 에이전트가 정의된 데이터 경계 내에서 작동하도록 보장하고 무단 데이터 노출을 방지하며 데이터 개인 정보 보호 규정을 준수하도록 유지합니다. 이는 기밀 또는 독점 정보를 처리하는 에이전트 AI 시스템에 대한 신뢰를 구축하는 데 가장 중요한 요소입니다.

추가로, 엔터프라이즈 데이터 소스에서 통합 데이터 속도 계층을 사용하면 에이전트 도구가 생성하는 리포지토리의 예기치 않은 임시 쿼리 부하를 완화할 수 있습니다. 한 곳에서 모든 것을 거의 실시간으로 검색하고 보안 및 거버넌스 제어를 적용할 수 있습니다.

하이브리드 검색 기반 도구

컨텍스트 엔지니어링의 추구를 가속화하는 Elastic 플랫폼의 몇 가지 핵심 기능( 계속 추가될 예정)이 있습니다. 여기서 가장 중요한 것은 플랫폼이 AI 생태계가 발전함에 따라 유연하게 적응, 변경, 확장할 수 있는 다양한 방법을 제공한다는 점입니다.

에이전트 빌더 소개

Elastic 에이전트 빌더는 Elastic에 이미 저장되어 있는 데이터와 채팅할 수 있도록 구축된 에이전트 AI 도구 영역에 처음으로 진출한 제품입니다. 에이전트 빌더는 사용자가 Kibana 내에서 자신만의 에이전트와 도구를 생성하고 관리할 수 있는 채팅 인터페이스를 제공합니다. 기본 제공 MCP 및 A2A 서버, 프로그래밍 방식의 API, Elasticsearch 인덱스를 쿼리 및 탐색하고 자연어로부터 ES|QL 쿼리를 생성하기 위한 사전 구축된 시스템 도구 세트가 함께 제공됩니다. 에이전트 빌더를 사용하면 표현식 ES|QL 쿼리 구문을 통해 에이전트에게 반환되는 컨텍스트 데이터를 타겟팅하고 조각하는 사용자 지정 도구를 만들 수 있습니다.

ES|QL은 하이브리드 검색을 어떻게 수행하나요? 핵심 기능은 semantic_text 필드 유형과 FORK/FUSE 명령의 조합을 통해 수행됩니다(FUSE는 기본적으로 각 포크의 결과를 병합하는 데 RRF를 사용합니다). 다음은 가상의 제품 검색에 대한 간단한 예제입니다:

FROM products
| FORK
  (MATCH description "high performance gaming laptop" | EVAL search_type = "bm25"),
  (MATCH description_semantic "high performance gaming laptop" | EVAL search_type = "semantic")
| FUSE 
| LIMIT 20
| KEEP product_name, description, _score, search_type

위의 예제에서 각 FORK 브랜치에 포함된 EVAL 절은 반드시 필요한 것은 아니며, 특정 검색 결과가 어떤 검색 방식에서 반환되었는지 추적하는 방법을 보여주기 위해 포함되었을 뿐입니다.

템플릿 검색

자체 외부 에이전트 도구를 Elastic 배포로 가리키고 싶다고 가정해 보겠습니다. 또한 ES|QL 대신 다단계 검색기를 사용하거나 개발한 기존 DSL 구문을 재사용하고 쿼리가 허용하는 입력, 검색 실행에 사용되는 구문 및 출력에 반환되는 필드를 제어할 수 있기를 원합니다. 검색 템플릿을 사용하면 일반적인 검색 패턴에 대해 미리 정의된 구조를 정의하여 데이터 검색의 효율성과 일관성을 개선할 수 있습니다. 이는 상용구 코드를 표준화하고 검색 로직의 빠른 반복을 가능하게 하므로 검색 API와 상호 작용하는 에이전트 도구에 특히 유용합니다. 이러한 요소 중 하나를 조정해야 하는 경우 검색 템플릿을 업데이트하기만 하면 변경 사항이 바로 적용됩니다. 에이전트 도구에서 작동하는 검색 템플릿의 예를 찾고 계신다면, 외부 MCP 서버에서 도구 호출 뒤에 검색 템플릿을 활용하는 Elasticsearch Labs 블로그 '지능형 검색을 위한 MCP'를 살펴보시기 바랍니다.

통합 워크플로(FTW!)

새로운 에이전트 AI 세계에서 가장 어려운 점 중 하나는 반자율적이고 자기 주도적인 '추론' 에이전트의 비결정적 특성입니다. 컨텍스트 엔지니어링은 에이전트 AI의 중요한 분야로, 에이전트가 생성할 수 있는 결론의 범위를 우리가 알고 있는 사실에 근거하여 좁히는 데 도움이 되는 기술입니다. 매우 정확하고 관련성이 높은 컨텍스트 창이 있더라도 (수치적 사실의 영역을 벗어나면) 상담원의 응답이 완전히 반복 가능하고 신뢰할 수 있다는 확신을 줄 수 있는 부분이 여전히 부족합니다.

상담원에게 동일한 요청을 여러 번 실행하면 응답에 약간의 차이가 있을 뿐 본질적으로 동일한 답변이 나올 수 있습니다. 이는 보통 눈에 띄지 않을 정도로 단순한 쿼리의 경우 괜찮으며 컨텍스트 엔지니어링 기법을 사용하여 결과물을 구체화할 수 있습니다. 하지만 상담원에게 요청하는 작업이 복잡해짐에 따라 하나 이상의 하위 작업으로 인해 최종 결과가 약간 달라질 수 있는 변수가 발생할 가능성이 커지고 있습니다. 상담원 간 커뮤니케이션에 더 많이 의존하기 시작하면 이러한 차이는 더욱 심해질 것이며, 이러한 차이는 누적될 것입니다. 이는 상담원이 상호작용하는 툴이 컨텍스트 데이터를 정확하게 타겟팅할 수 있도록 매우 유연하고 조정이 가능해야 하며, 예상 출력 형식으로 응답해야 한다는 점을 다시 한 번 강조합니다. 또한 많은 사용 사례에서 에이전트와 툴의 상호 작용을 지시해야 할 필요가 있음을 나타내며, 바로 여기에서 워크플로우가 등장합니다!

Elastic은 곧 플랫폼의 핵심에 완전히 사용자 정의 가능한 워크플로우를 내장할 예정입니다. 이러한 워크플로는 상담원 및 툴과 양방향으로 작동할 수 있으므로 워크플로는 상담원 및 툴을 호출할 수 있고, 상담원 및 툴은 워크플로를 호출할 수 있게 됩니다. 이러한 기능이 모든 데이터가 있는 동일한 검색 AI 플랫폼에 완전히 통합되어 워크플로우를 혁신적으로 변화시킬 수 있는 잠재력은 매우 흥미롭습니다! 곧 출시됩니다!

통합 메모리 뱅크로서의 Elastic

실시간에 가까운 검색을 위해 만들어진 분산 데이터 플랫폼이기 때문에, Elastic은 에이전트 AI 시스템을 위한 장기 메모리 기능을 자연스럽게 수행합니다. 기본 제공되는 상담원 빌더 채팅 환경을 통해 단기 기억 및 채팅 기록을 추적하고 관리할 수도 있습니다. 그리고 전체 플랫폼이 API 우선이기 때문에, 에이전트의 컨텍스트 창을 압도할 수 있는 도구의 컨텍스트 출력을 유지(그리고 나중에 참조할 수 있도록)하기 위한 플랫폼으로 Elastic을 매우 쉽게 활용할 수 있습니다. 이 기술은 컨텍스트 엔지니어링 업계에서 "메모 작성"이라고도 불립니다.

동일한 검색 플랫폼에서 단기 메모리와 장기 메모리를 모두 사용하면 많은 본질적인 이점을 얻을 수 있습니다. 채팅 기록과 지속적 문맥 반응을 향후 채팅 상호작용에 시맨틱 영향력의 일부로 사용하거나 위협 분석을 수행하거나 자주 반복되는 도구 호출에서 자동으로 생성되는 지속적 데이터 제품을 만들 수 있다고 상상해 보세요... 가능성은 무궁무진합니다!

결론

대규모 언어 모델의 등장으로 콘텐츠를 매칭하는 방식과 데이터를 조사하는 방법이 바뀌었습니다. 사람이 직접 조사하고, 맥락을 고려하고, 논리적 추론을 통해 질문에 답하는 현재의 세상에서 에이전트 AI를 통해 이러한 단계가 대부분 자동화되는 세상으로 빠르게 전환되고 있습니다. 생성된 답변을 신뢰할 수 있으려면 상담원이 답변을 생성할 때 가장 관련성이 높은 모든 정보(주관적 관련성 요소 포함)를 고려했다는 확신이 있어야 합니다. 에이전트 AI를 신뢰할 수 있게 만드는 기본 방법은 RAG 및 컨텍스트 엔지니어링 기술을 통해 추가 컨텍스트를 검색하는 도구를 기반으로 하는 것이지만, 이러한 도구가 초기 검색을 수행하는 방식은 응답의 정확성에 매우 중요할 수 있습니다.

Elastic Search AI 플랫폼은 정확성, 성능, 확장성 측면에서 에이전트 AI를 지원하는 여러 기본 제공 기능과 함께 하이브리드 검색의 유연성과 이점을 제공합니다. 즉, Elastic은 컨텍스트 엔지니어링의 여러 측면을 위한 환상적인 플랫폼입니다! 검색 플랫폼을 통해 컨텍스트 검색을 표준화함으로써 여러 측면에서 에이전트 도구 운영을 간소화하며, '느려야 빨리 간다'는 모순처럼 컨텍스트 생성 계층에서의 간소화는 더 빠르고 더 신뢰할 수 있는 에이전트 AI를 의미합니다.

데이터와 상호 작용하는 새로운 방법

제너레이티브(genAI) 및 에이전트 AI는 기존 검색과는 다른 방식으로 작업을 수행합니다. 과거에는 검색("구글에 검색해 볼게요...")을 통해 정보 조사를 시작했지만, 세대별 AI와 상담원 모두 채팅 인터페이스에 자연어를 입력하는 것이 시작 작업의 대부분을 차지합니다. 채팅 인터페이스는 LLM과의 토론으로, 의미론적 이해를 바탕으로 우리의 질문을 모든 종류의 정보에 대한 폭넓은 지식을 가진 오라클이 제공하는 것처럼 보이는 요약된 답변으로 바꿔줍니다. LLM의 진정한 매력은 드러나는 지식의 조각들을 하나로 묶어 일관성 있고 사려 깊은 문장을 만들어내는 능력입니다. 부정확하거나 완전히 환각적인 내용일지라도 진실성이 담겨 있습니다.

우리가 익숙한 검색창은 우리가 직접 추론 에이전트였을 때 사용했던 RAG 엔진이라고 생각할 수 있습니다. 이제 인터넷 검색 엔진도 기존의 '사냥과 쪼기' 방식의 어휘 검색 경험을 AI 기반 개요로 전환하여 검색어에 대한 답변과 결과 요약을 제공함으로써 사용자가 개별 결과를 직접 클릭하고 평가할 필요가 없도록 돕고 있습니다.

제너레이티브 AI & RAG

생성형 AI는 세상에 대한 의미론적 이해를 바탕으로 채팅 요청에 명시된 주관적 의도를 분석한 다음 추론 능력을 사용하여 즉석에서 전문가 답변을 생성합니다. 생성형 AI 상호작용에는 사용자의 입력/질문으로 시작하여 채팅 세션의 이전 대화를 추가 컨텍스트로 사용할 수 있으며, LLM에 추론 방법과 응답을 구성할 때 따라야 할 절차를 알려주는 지시 프롬프트 등 여러 부분이 있습니다. 안내 메시지는 " "5살짜리 아이처럼 설명해 주세요"라는 단순한 안내에서 요청 처리 방법에 대한 완전한 분석으로 발전했습니다. 이러한 분류에는 종종 AI의 페르소나/역할, 생성 전 추론/내부 사고 과정, 객관적 기준, 제약 조건, 출력 형식, 대상에 대한 세부 사항을 설명하는 별도의 섹션과 예상 결과를 입증하는 데 도움이 되는 예시가 포함됩니다.

검색 증강 생성(RAG)은 사용자의 쿼리와 시스템 프롬프트 외에도 "컨텍스트 창"이라고 하는 추가 컨텍스트 정보를 제공합니다. RAG는 아키텍처에 중요한 추가 기능으로, LLM이 세계를 의미론적으로 이해하는 데 있어 누락된 부분을 알려주는 데 사용됩니다.

컨텍스트 창은 무엇을, 어디에, 얼마나 제공해야 하는지에 대해 다소 까다로울 수 있습니다. 물론 어떤 컨텍스트가 선택되는지도 매우 중요하지만, 제공된 컨텍스트의 신호 대 잡음비와 창 길이도 중요합니다.

너무 적은 정보

쿼리, 프롬프트 또는 컨텍스트 창에 너무 적은 정보를 제공하면 LLM이 응답을 생성할 올바른 의미적 컨텍스트를 정확하게 판단할 수 없기 때문에 착각이 발생할 수 있습니다. 문서 청크 크기의 벡터 유사성에도 문제가 있습니다. 짧고 간단한 질문이 벡터화된 지식창고에 있는 풍부하고 상세한 문서와 의미적으로 일치하지 않을 수 있습니다. 가상의 문서 임베딩(HyDE) 과 같은 쿼리 확장 기법이 개발되어 LLM을 사용하여 짧은 쿼리보다 더 풍부하고 표현력이 풍부한 가상의 답변을 생성할 수 있습니다. 물론 여기서 위험은 가상의 문서 자체가 올바른 맥락에서 더욱 멀어지게 하는 환각이라는 점입니다.

너무 많은 정보

우리 인간과 마찬가지로, 컨텍스트 창에 너무 많은 정보가 있으면 LLM이 중요한 부분이 무엇인지 압도당하고 혼란스러워할 수 있습니다. 컨텍스트 오버플로(또는 "컨텍스트 썩음")는 생성 AI 작업의 품질과 성능에 영향을 미치며, LLM의 "주의 예산"(작업 메모리)에 큰 영향을 미치고 여러 경쟁 토큰 간의 관련성을 희석시킵니다. '컨텍스트 썩음'의 개념에는 LLM이 중간 섹션의 콘텐츠보다 컨텍스트 창의 시작 또는 끝에 있는 콘텐츠를 선호하는 위치 편향이 있다는 관찰 결과도 포함됩니다.

산만하거나 상충되는 정보

컨텍스트 창이 커질수록 불필요하거나 상충되는 정보가 포함될 가능성이 높아져 LLM이 올바른 컨텍스트를 선택하고 처리하는 데 방해가 될 수 있습니다. 어떤 면에서는 가비지 인/가비지 아웃의 문제가 됩니다. 문서 결과 집합을 컨텍스트 창에 덤핑하는 것만으로도 LLM이 처리해야 할 정보가 너무 많지만, 컨텍스트가 어떻게 선택되었는지에 따라 상충되거나 관련 없는 정보가 스며들 가능성이 더 커질 수 있기 때문입니다.

에이전틱 AI

다뤄야 할 내용이 많다고 말씀드렸지만, 드디어 에이전트 AI 주제에 대해 이야기하게 되었습니다! 에이전트 AI는 사용자가 제공한 지식과 문맥 정보를 바탕으로 답변을 합성하는 제너레이티브 AI의 (이미 '레거시'라고 불러도 될까요?) 기능을 확장한 LLM 채팅 인터페이스의 매우 흥미로운 새로운 사용법입니다. 제너레이티브 AI가 더욱 성숙해지면서 처음에는 사람이 쉽게 확인/검증할 수 있는 지루하고 위험도가 낮은 활동으로 한정했던 작업을 LLM이 수행할 수 있는 일정 수준의 작업과 자동화가 가능하다는 것을 깨달았습니다. 짧은 기간 동안 초기 범위가 확장되어 이제 LLM 채팅 창은 AI 에이전트가 자율적으로 계획을 수립하고 실행하며 지정된 목표를 달성하기 위해 계획을 반복적으로 평가하고 조정하도록 하는 촉매제가 될 수 있습니다. 상담원은 LLM의 추론, 채팅 기록 및 사고 기억(있는 그대로)에 액세스할 수 있으며, 이러한 목표를 위해 활용할 수 있는 특정 도구도 마련되어 있습니다. 또한 최상위 에이전트가 각각 고유한 로직 체인, 명령어 세트, 컨텍스트 및 도구를 갖춘 여러 하위 에이전트의 오케스트레이터로 기능할 수 있는 아키텍처도 등장하고 있습니다.

상담원은 대부분 자동화된 워크플로우의 시작점으로, 사용자와 채팅한 다음 '로직'을 사용하여 사용자의 질문에 답할 수 있는 도구를 결정할 수 있다는 점에서 자기 주도적입니다. 도구는 일반적으로 에이전트에 비해 수동적인 것으로 간주되며 한 가지 유형의 작업을 수행하도록 만들어집니다. 툴이 수행할 수 있는 작업의 유형은 무궁무진하지만(정말 흥미롭습니다!) 툴이 수행하는 주요 작업은 상담원이 워크플로우를 실행할 때 고려할 수 있도록 컨텍스트 정보를 수집하는 것입니다.

에이전트 AI는 아직 초기 단계의 기술로서 주의력 결핍 장애에 해당하는 LLM에 취약하며, 요청받은 작업을 쉽게 잊어버리고 업무에 전혀 포함되지 않은 다른 일을 하러 도망가는 경우가 많습니다. 겉보기에는 마술처럼 보이지만, LLM의 '추론' 능력은 여전히 시퀀스에서 다음으로 가능성이 높은 토큰을 예측하는 것을 기반으로 합니다. 추론(또는 언젠가는 인공 일반 지능(AGI)이)이 신뢰할 수 있고 신뢰할 수 있으려면 정확한 최신 정보가 주어졌을 때 우리가 기대하는 방식으로 추론할 수 있는지(그리고 우리가 미처 생각하지 못했던 것을 조금 더 제공할 수도 있는지) 검증할 수 있어야 합니다. 이를 위해서는 에이전트 아키텍처가 명확하게 커뮤니케이션하고(프로토콜), 워크플로와 제약 조건을 준수하며(가드레일), 작업의 현재 위치를 기억하고(상태), 사용 가능한 메모리 공간을 관리하고, 응답이 정확하고 작업 기준을 충족하는지 검증할 수 있는 기능이 필요합니다.

내가 이해할 수 있는 언어로 대화하기

새로운 개발 영역에서 흔히 그렇듯이(특히 LLM의 세계에서는 더욱 그렇습니다) 처음에는 에이전트 간 커뮤니케이션을 위한 여러 가지 접근 방식이 있었지만, 사실상의 표준인 모델 컨텍스트 프로토콜(MCP) 로 빠르게 수렴되었습니다. 모델 컨텍스트 프로토콜의 정의는 이름 그대로 모델이 컨텍스트 정보를 요청하고 수신하는 데 사용하는 프로토콜입니다. MCP는 LLM 에이전트가 외부 도구 및 데이터 소스에 연결할 수 있는 범용 어댑터 역할을 하며, 서로 다른 LLM 프레임워크와 도구가 쉽게 상호 운용될 수 있도록 API를 단순화하고 표준화합니다. 따라서 MCP는 에이전트가 목표를 달성하기 위해 자율적으로 수행하도록 에이전트에 제공되는 오케스트레이션 로직 및 시스템 프롬프트와 보다 격리된 방식으로 수행하도록 툴로 전송되는 작업(적어도 시작 에이전트와 관련해서는 격리된) 사이의 일종의 구심점 역할을 합니다.

이 에코시스템은 모든 방향이 새로운 개척지처럼 느껴질 정도로 모든 것이 새롭습니다. 에이전트 간 상호작용을 위한 유사한 프로토콜(에이전트2에이전트(A2A) natch!)과 에이전트 추론 메모리 개선(ReasoningBank), 현재 작업에 가장 적합한 MCP 서버 선택(RAG-MCP), 입력 및 출력의 제로 샷 분류 및 패턴 감지 등의 의미 분석을 가드레일로 사용하여 에이전트의 작업 허용 대상을 제어하기 위한 다른 프로젝트도 있습니다.

이러한 각 프로젝트의 기본 의도가 에이전트/genAI 컨텍스트 창에 반환되는 정보의 품질과 제어를 개선하는 것임을 눈치채셨나요? 에이전트 AI 생태계가 컨텍스트 정보를 더 잘 처리(제어, 관리 및 운영)할 수 있는 기능을 계속 개발하는 동안에도 에이전트가 밀링할 수 있는 가장 관련성 높은 컨텍스트 정보를 검색해야 할 필요성은 항상 존재할 것입니다.