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

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

사전 준비 사항#

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

1. Azure 구독

2. Azure AI Search 서비스

3. API 키 인증 구성(쓰기 작업용 관리자 키, 읽기 전용 작업용 쿼리 키)

   설정 방법은 자격 증명 문서를 참고하세요.

인덱스 구성#

노드는 인덱스가 존재하지 않는 경우 자동으로 생성합니다. 자동 생성 시 노드는 다음을 구성합니다:

• 사용 중인 임베딩 모델에 따라 적절한 차원을 갖는 벡터 필드
• 코사인 메트릭을 사용한 효율적인 유사도 검색을 위한 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 에이전트의 도구 커넥터에 연결하여 벡터 스토어를 검색 가능한 지식 베이스로 사용합니다:

AI 에이전트(도구 커넥터) → Azure AI Search Vector Store 노드

리트리버를 사용하여 문서 가져오기#

검색 증강 생성(retrieval-augmented generation)을 위해 Vector Store Retriever 및 Question and Answer Chain과 함께 사용하세요:

Question and Answer Chain(리트리버) → Vector Store Retriever(벡터 스토어) → Azure AI Search Vector Store

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

Vector Store Question Answer Tool 사용#

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

AI 에이전트(도구) → Vector Store Question Answer Tool(벡터 스토어) → Azure AI Search Vector Store

이 예시를 참고하세요.

노드 매개변수#

결과 재정렬#

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 매개변수(체인/도구용 벡터 스토어)#

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

Retrieve Documents(AI 에이전트용 도구) 매개변수#

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

노드 옵션#

옵션#

• Filter: 문서 필드 또는 메타데이터로 결과를 필터링하기 위한 OData 필터 표현식. 아래 필터 예시를 참고하세요.
• Query Mode: 사용할 검색 전략:
  • Vector: 임베딩만 사용하는 유사도 검색
  • Keyword: BM25 랭킹을 사용하는 전문(full-text) 검색
  • Hybrid(기본값): 벡터 검색과 키워드 검색을 상호 순위 융합(Reciprocal Rank Fusion, RRF)으로 결합
  • Semantic 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를 사용한 하이브리드 검색#

Azure AI Search의 하이브리드 검색은 상호 순위 융합(Reciprocal Rank Fusion)을 사용하여 벡터 결과와 키워드 결과를 병합함으로써 어느 한 방법만 사용하는 것보다 더 나은 정확도를 제공합니다.

시맨틱 랭킹#

Semantic Hybrid 모드는 쿼리에 대한 시맨틱 이해를 바탕으로 결과를 재순위화하기 위해 머신러닝 모델을 적용합니다. 이를 위해서는 인덱스에 시맨틱 구성이 필요합니다.

OData 필터#

벡터 검색이 실행되기 전에 문서 필드 또는 메타데이터로 필터링하려면 OData 구문을 사용하세요. 특정 소스나 특정 속성을 가진 결과가 필요할 때 성능과 정확도를 개선할 수 있습니다.

HNSW 알고리즘#

Azure AI Search는 근사 최근접 이웃(approximate nearest neighbor) 검색을 위해 계층적 탐색 가능 소규모 세계(Hierarchical Navigable Small World, HNSW) 그래프를 사용하여, 정확도와 속도를 조절 가능한 대규모 환경에서 빠른 조회를 제공합니다.

문제 해결#

인덱스 문제#

인덱스를 찾을 수 없음: 인덱스 이름이 올바른지(대소문자 구분) 확인하고 Azure AI Search 서비스에 해당 인덱스가 존재하는지 확인하세요. 자동 생성을 사용 중이라면 인덱스가 정상적으로 생성되었는지 확인하세요.

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

문서 삽입 실패:

• 쓰기 권한을 확인하세요(관리자 API 키 필요)
• 문서 필드가 인덱스 스키마와 일치하는지 확인하세요
• 필수 필드가 문서에 포함되어 있는지 확인하세요
• 대량 문서 세트에서 타임아웃이 발생하는 경우 배치 크기 설정을 검토하세요

필터 문제#

필터가 작동하지 않음:

• 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 서비스가 실행 중이고 접근 가능한지 확인하세요
• 네트워크 보안 그룹, 방화벽 규칙, 프라이빗 엔드포인트 구성을 확인하세요
• Azure에서 호스팅되는 n8n의 경우, 프라이빗 엔드포인트를 사용 중이라면 가상 네트워크 피어링 또는 서비스 엔드포인트 구성을 확인하세요

인증 문제#

API 키 오류 등 인증 문제 해결에 대해서는 자격 증명 문서의 문제 해결 섹션을 참고하세요.

템플릿 및 예시#

Azure AI Search Vector Store 노드 문서 통합 템플릿 둘러보기 또는 전체 템플릿 검색

관련 리소스#

• Azure AI Search Vector Search 문서
• LangChain Azure AI Search 통합
• Azure AI Search REST API 참조
• Azure AI Search용 OData 필터 구문