Azure AI Search(구 Azure Cognitive Search)는 RAG 및 시맨틱 검색 애플리케이션을 위한 벡터 검색 기능을 갖춘 클라우드 검색 서비스입니다. 이 노드를 사용하여 벡터 임베딩을 콘텐츠 및 메타데이터와 함께 저장, 검색, 쿼리할 수 있습니다.

이 페이지에서는 Azure AI Search Vector Store 노드의 파라미터와 추가 리소스 링크를 확인할 수 있습니다.

사전 요구 사항#

이 노드를 사용하기 전에 다음이 필요합니다:

1. Azure 구독

2. Azure AI Search 서비스

3. API 키 인증 구성 (쓰기 작업에는 admin key, 읽기 전용에는 query key 사용)

   설정 방법은 인증 정보 문서를 참고하세요.

인덱스 구성#

노드는 인덱스가 존재하지 않으면 자동으로 생성합니다. 자동 생성 시 노드는 다음과 같이 구성합니다:

• 임베딩 모델에 맞는 적절한 차원의 벡터 필드
• cosine 메트릭을 사용하는 효율적인 유사도 검색을 위한 HNSW 알고리즘
• 필터링 및 검색을 위한 콘텐츠 및 메타데이터 필드

사용자 지정 구성을 위해 Azure Portal에서 인덱스를 미리 생성할 수도 있습니다. 예시 스키마:

{
  "name": "n8n-vectorstore",
  "fields": [
    {
      "name": "id",
      "type": "Edm.String",
      "key": true,
      "filterable": true
    },
    {
      "name": "content",
      "type": "Edm.String",
      "searchable": true
    },
    {
      "name": "content_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "vectorSearchDimensions": 1536,
      "vectorSearchProfileName": "n8n-vector-profile"
    },
    {
      "name": "metadata",
      "type": "Edm.String",
      "filterable": true
    }
  ],
  "vectorSearch": {
    "profiles": [
      {
        "name": "n8n-vector-profile",
        "algorithm": "n8n-vector-algorithm"
      }
    ],
    "algorithms": [
      {
        "name": "n8n-vector-algorithm",
        "kind": "hnsw",
        "hnswParameters": {
          "metric": "cosine",
          "m": 4,
          "efConstruction": 400,
          "efSearch": 500
        }
      }
    ]
  }
}

노드 사용 패턴#

일반 노드로 사용하여 문서 삽입 및 검색#

에이전트 없이 워크플로에서 노드를 직접 사용하여 문서를 삽입하거나 검색합니다. 패턴 예시는 이 템플릿을 참고하세요(Supabase를 사용하지만 패턴은 동일합니다).

AI 에이전트에 도구로 직접 연결#

AI 에이전트의 tool connector에 연결하여 벡터 스토어를 검색 가능한 지식 베이스로 사용합니다:

AI 에이전트 (tools connector) → Azure AI Search Vector Store 노드

retriever를 사용하여 문서 가져오기#

검색 증강 생성(RAG)을 위해 Vector Store Retriever 및 Question and Answer Chain과 함께 사용합니다:

Question and Answer Chain (Retriever) → Vector Store Retriever (Vector Store) → Azure AI Search Vector Store

예시 워크플로를 참고하세요.

Vector Store Question Answer Tool 사용#

Vector Store Question Answer Tool을 사용하여 요약하고 질문에 답변합니다:

AI 에이전트 (tools) → Vector Store Question Answer Tool (Vector Store) → Azure AI Search Vector Store

이 예시를 참고하세요.

노드 파라미터#

이 Vector Store 노드에는 다섯 가지 모드가 있습니다: 여러 개 가져오기(Get Many), 문서 삽입(Insert Documents), 문서 검색(체인/도구용 벡터 스토어로 사용)(Retrieve Documents (As Vector Store for Chain/Tool)), 문서 검색(AI 에이전트용 도구로 사용)(Retrieve Documents (As Tool for AI Agent)), 문서 업데이트(Update Documents). 선택한 모드에 따라 노드에서 수행할 수 있는 작업과 사용 가능한 입력 및 출력이 결정됩니다.

여러 개 가져오기(Get Many)#

이 모드에서는 프롬프트를 제공하여 벡터 데이터베이스에서 여러 문서를 검색할 수 있습니다. 프롬프트는 임베딩되어 유사도 검색에 사용됩니다. 노드는 프롬프트와 가장 유사한 문서를 유사도 점수와 함께 반환합니다. 유사한 문서 목록을 검색하여 에이전트에 추가 컨텍스트로 전달하려는 경우에 유용합니다.

문서 삽입(Insert Documents)#

문서 삽입 모드를 사용하여 벡터 데이터베이스에 새 문서를 삽입합니다.

문서 검색(체인/도구용 벡터 스토어로 사용)(Retrieve Documents (As Vector Store for Chain/Tool))#

벡터 스토어 리트리버와 함께 문서 검색(체인/도구용 벡터 스토어로 사용) 모드를 사용하여 벡터 데이터베이스에서 문서를 검색하고 체인에 연결된 리트리버에 제공합니다. 이 모드에서는 노드를 리트리버 노드 또는 루트 노드에 연결해야 합니다.

문서 검색(AI 에이전트용 도구로 사용)(Retrieve Documents (As Tool for AI Agent))#

쿼리에 답변할 때 벡터 스토어를 도구 리소스로 사용하려면 문서 검색(AI 에이전트용 도구로 사용) 모드를 사용합니다. 응답을 구성할 때 에이전트는 벡터 스토어 이름과 설명이 질문 내용과 일치하는 경우 벡터 스토어를 사용합니다.

문서 업데이트(Update Documents)#

ID로 벡터 데이터베이스의 문서를 업데이트하려면 문서 업데이트 모드를 사용합니다. 업데이트할 임베딩 항목의 ID를 ID 필드에 입력합니다.

Rerank Results#

재순위 지정(reranking)을 활성화합니다. 이 옵션을 활성화하면 벡터 스토어에 재순위 지정 노드를 연결해야 합니다. 해당 노드가 쿼리 결과를 재순위 지정합니다. 이 옵션은 여러 개 가져오기(Get Many), 문서 검색(체인/도구용 벡터 스토어로 사용)(Retrieve Documents (As Vector Store for Chain/Tool)), 문서 검색(AI 에이전트용 도구로 사용)(Retrieve Documents (As Tool for AI Agent)) 모드와 함께 사용할 수 있습니다.

Get Many 파라미터#

• Endpoint: Azure AI Search 엔드포인트 (형식: https://your-service.search.windows.net)
• Index Name: 쿼리할 인덱스
• Limit: 반환할 최대 문서 수 (기본값: 4)

Insert Documents 파라미터#

• Endpoint: Azure AI Search 엔드포인트
• Index Name: 사용할 인덱스 (존재하지 않으면 자동 생성)
• Batch Size: Azure AI Search에 한 번에 업로드할 문서 수. 문서 크기와 서비스 티어 제한에 따라 조정하세요. 업로드 배치 처리만 제어하며, 임베딩 생성 배치 처리는 임베딩 노드에서 구성합니다.

Update Documents 파라미터#

• Endpoint: Azure AI Search 엔드포인트
• Index Name: 업데이트할 인덱스

Retrieve Documents 파라미터 (Chain/Tool용 Vector Store로 사용 시)#

• Endpoint: Azure AI Search 엔드포인트
• Index Name: 쿼리할 인덱스

Retrieve Documents (AI 에이전트용 Tool로 사용 시) 파라미터#

• Name: LLM에 표시되는 도구 이름
• Description: LLM에 이 도구의 용도를 설명합니다. LLM이 언제 사용할지 판단할 수 있도록 구체적으로 작성하세요.
• Endpoint: Azure AI Search 엔드포인트
• Index Name: 쿼리할 인덱스
• Limit: 검색할 최대 결과 수 (예: 상위 10개 일치 항목의 경우 10)

노드 옵션#

옵션#

• Filter: 문서 필드 또는 메타데이터로 결과를 필터링하는 OData 필터 표현식. 아래 필터 예시를 참고하세요.
• Query Mode: 사용할 검색 전략:
  • Vector: 임베딩만 사용하는 유사도 검색
  • Keyword: BM25 랭킹을 사용하는 전문 검색
  • Hybrid (기본값): Reciprocal Rank Fusion(RRF)을 사용하여 벡터와 키워드 검색을 결합
  • Semantic Hybrid: 향상된 관련성을 위한 시맨틱 재랭킹이 포함된 Hybrid 검색
• Semantic Configuration: 시맨틱 랭킹에 사용할 시맨틱 구성 이름. 지정하지 않으면 semantic-search-config로 기본 설정됩니다. 사용자 지정 시맨틱 구성 이름으로 인덱스를 미리 생성한 경우에만 필요합니다.

OData 필터 예시#

Azure AI Search는 필터링에 OData 구문을 사용합니다. 메타데이터 필드는 metadata/fieldName 형식으로 접근합니다.

문서 ID로 필터링:

id eq '3da6491a-f930-4a4e-9471-c05dcd450ba0'

메타데이터 필드로 필터링:

metadata/source eq 'user-guide'

복합 AND 필터:

metadata/category eq 'technology' and metadata/author eq 'John'

복합 OR 필터:

metadata/source eq 'user-guide' or metadata/rating ge 4

숫자 비교:

metadata/rating ge 4 and metadata/rating lt 10

NOT을 사용한 문자열 매칭:

metadata/category eq 'technology' and metadata/title ne 'Deprecated'

지원되는 OData 연산자:

• 비교: eq, ne, gt, ge, lt, le
• 논리: and, or, not
• 문자열 함수: startswith(), endswith(), contains()
• 컬렉션 함수: any(), all()

Azure AI Search 특화 기능#

RRF를 사용한 Hybrid 검색#

Azure AI Search의 Hybrid 검색은 Reciprocal Rank Fusion을 사용하여 벡터와 키워드 결과를 병합하여, 각 방법 단독보다 더 높은 정확도를 제공합니다.

시맨틱 랭킹#

Semantic Hybrid 모드는 머신러닝 모델을 적용하여 쿼리의 시맨틱 이해를 기반으로 결과를 재랭킹합니다. 이 기능을 사용하려면 인덱스에 시맨틱 구성이 필요합니다.

OData 필터#

OData 구문을 사용하여 벡터 검색 실행 전에 문서 필드 또는 메타데이터로 필터링합니다. 특정 소스나 특정 속성을 가진 결과가 필요할 때 성능과 정밀도를 향상시킵니다.

HNSW 알고리즘#

Azure AI Search는 근사 최근접 이웃 검색을 위해 Hierarchical Navigable Small World(HNSW) 그래프를 사용하여, 정확도/속도 균형을 조정할 수 있는 빠른 대규모 검색을 제공합니다.

문제 해결#

인덱스 문제#

인덱스를 찾을 수 없음: 인덱스 이름이 정확한지(대소문자 구분) Azure AI Search 서비스에 존재하는지 확인하세요. 자동 생성을 사용하는 경우 인덱스가 성공적으로 생성되었는지 확인하세요.

벡터 차원 불일치: 임베딩 모델의 차원이 인덱스 벡터 필드 차원과 일치하는지 확인하세요. 인덱스 스키마에서 vectorSearchDimensions 설정을 확인하세요.

문서 삽입 실패:

• 쓰기 권한 확인 (admin API key 필요)
• 문서 필드가 인덱스 스키마와 일치하는지 확인
• 문서에 필수 필드가 제공되는지 확인
• 대용량 문서 세트에서 타임아웃이 발생하면 batch size 설정 검토

필터 문제#

필터가 작동하지 않음:

• OData 구문이 올바른지 확인
• 메타데이터 필드에 metadata/ 접두사 사용 확인: metadata/source eq 'value'
• 필터링된 필드가 인덱스 스키마에서 filterable로 표시되었는지 확인
• 복잡한 표현식 전에 단순한 필터(id eq 'value')로 먼저 테스트

잘못된 OData 구문:

• 문자열 값에 작은따옴표 사용: metadata/source eq 'value'
• 올바른 연산자 사용: eq, ne, gt, ge, lt, le, and, or, not
• 구문 세부 사항은 OData 필터 문서 참고

연결 문제#

연결 불가:

• 엔드포인트 URL 형식 확인: https://your-service.search.windows.net
• Azure AI Search 서비스가 실행 중이고 접근 가능한지 확인
• 네트워크 보안 그룹, 방화벽 규칙, private endpoint 구성 확인
• Azure 호스팅 n8n의 경우, private endpoint 사용 시 가상 네트워크 피어링 또는 서비스 엔드포인트 구성 확인

인증 문제#

API 키 오류를 포함한 인증 문제 해결은 인증 정보 문서 문제 해결 섹션을 참고하세요.

템플릿 및 예제#

관련 리소스#

• Azure AI Search 벡터 검색 문서
• LangChain Azure AI Search 통합
• Azure AI Search REST API 참고 문서
• Azure AI Search OData 필터 구문

n8n의 Advanced AI 문서를 확인하세요.

셀프 호스팅 AI 스타터 킷#

AI 작업과 셀프 호스팅 n8n이 처음이신가요? Ollama, Qdrant, PostgreSQL을 활용한 개념 증명(PoC) 또는 데모 플레이그라운드를 시작하려면 n8n의 셀프 호스팅 AI 스타터 킷을 사용해 보세요.