Databricks Vector Store 노드
n8n v2.47요약
Databricks Vector Store 노드를 사용하여 워크플로에서 Databricks Vector Search 인덱스를 다룰 수 있습니다. 이 페이지에서는 사전 요구 사항, 노드가 다루는 인덱스 유형, 노드 파라미터와 옵션, 그리고 실제 예제를 설명합니다.
Databricks Vector Store 노드를 사용하여 워크플로에서 Databricks Vector Search 인덱스를 다룰 수 있습니다. 인덱스에 대해 유사도 검색을 실행하거나, Direct Access 인덱스에 문서를 삽입하거나, 체인1에 연결된 리트리버에 인덱스를 전달하거나, 도구2로 사용하기 위해 AI 에이전트3에 연결할 수 있습니다. 인덱스는 Unity Catalog에 있으므로, 노드에서는 자격 증명의 ID가 접근할 수 있는 데이터만 볼 수 있습니다.
이 페이지에서는 사전 요구 사항, 노드가 다루는 인덱스 유형, 노드 파라미터와 옵션, 그리고 실제 예제를 설명합니다. n8n-nodes-databricks 커뮤니티 패키지에서 넘어오는 경우 커뮤니티 패키지에서 마이그레이션을 참조하세요.
자격 증명
인증 설정 방법은 Databricks 자격 증명을 참조하세요. 이 노드는 서비스 주체 또는 사용자 로그인을 사용하는 Databricks OAuth2 API 자격 증명만 허용합니다. 개인 액세스 토큰은 허용하지 않습니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
사전 요구 사항#
- Vector Search 엔드포인트와 그 위의 인덱스가 하나 이상 있는 Databricks 워크스페이스. Databricks 문서의 벡터 검색 인덱스 생성 및 쿼리를 참조하세요.
- n8n의 Databricks OAuth2 자격 증명. 서비스 주체 또는 사용자 로그인을 사용합니다.
- 노드의 Embedding 입력에 연결된 Embeddings Databricks 노드. Databricks가 임베딩을 직접 계산하는 인덱스에서도 모든 작업 모드에서 이 입력이 필요합니다. 인덱스 유형과 임베딩을 참조하세요.
- 자격 증명이 인증하는 ID에 필요한 권한은 다음과 같습니다.
- 인덱스가 있는 카탈로그의 USE CATALOG와 스키마의 USE SCHEMA.
- 인덱스의 SELECT. Insert Documents에는 인덱스의 MODIFY도 필요합니다.
- 모든 칼럼을 동기화하는 Delta Sync 인덱스의 소스 테이블에 대한 SELECT. 노드가 Content Column과 Metadata Columns에 칼럼 목록을 표시하는 데 필요합니다. 이 권한이 없으면 Metadata Columns가 비어 있고, Content Column에는 임베딩 소스 칼럼만 표시되며, 문서는 콘텐츠만 포함해 반환됩니다.
- Embeddings Databricks 노드가 사용하는 임베딩 모델 서비스가 있는 카탈로그와 스키마의 USE CATALOG와 USE SCHEMA, 그리고 해당 서비스의 EXECUTE. Databricks는
system.ai서비스의 EXECUTE를 기본적으로 모든 사용자에게 부여합니다. - Metadata Filter를 사용하는 경우, 인덱스를 제공하는 Vector Search 엔드포인트에 대한 읽기 권한. 노드는 필터가 적용되는지 확인하기 위해 실행마다 한 번 엔드포인트 유형을 읽습니다. 워크스페이스 사용자에게는 기본적으로 이 권한이 있습니다.
서비스 주체는 Workspace access 권한(entitlement)이 있는 워크스페이스 멤버여야 합니다. 계정 수준에만 존재하는 서비스 주체는 워크스페이스 토큰 엔드포인트에서 invalid_client로 실패하며, 이는 클라이언트 시크릿이 잘못된 것처럼 보입니다. 전체 목록은 필요한 Databricks 권한을 참조하세요.
인덱스 유형과 임베딩#
Databricks 인덱스의 두 가지 속성이 노드가 인덱스로 할 수 있는 작업을 결정합니다. 행이 인덱스에 들어오는 방식과, 임베딩을 누가 계산하는지입니다. 노드는 실행마다 한 번 인덱스 설명을 읽고 두 속성에 맞게 동작합니다. 쿼리 모드를 직접 선택할 필요는 없습니다.
Delta Sync 및 Direct Access 인덱스#
| 인덱스 유형 | 행의 출처 | Insert Documents |
|---|---|---|
| Delta Sync | Databricks가 인덱스와 동기화 상태로 유지하는 Delta 테이블 | 지원하지 않습니다. 대신 소스 테이블에 행을 추가하세요. 노드는 쓰기 전에 Index <name> syncs from its source table. Use a Direct Access index to insert documents 오류로 실패합니다. |
| Direct Access | Vector Search API로 직접 쓰는 행 | 지원합니다. Insert Documents 모드에서는 Index 목록에 Direct Access 인덱스만 표시됩니다. |
세 가지 검색 모드는 두 인덱스 유형 모두에서 동작합니다. Insert Documents는 Direct Access 인덱스에서만 동작합니다.
관리형 및 자체 관리형 임베딩#
| 임베딩 | 텍스트를 임베딩하는 주체 | 노드가 보내는 값 | Embeddings Databricks 노드 |
|---|---|---|---|
| 관리형: Databricks 임베딩 모델을 사용하는 Delta Sync 인덱스 | 인덱스의 임베딩 소스 칼럼을 사용하는 Databricks | query_text로 보내는 검색 텍스트 |
연결은 하지만 호출되지 않음 |
| 자체 관리형: Direct Access 인덱스, 또는 자체 벡터 칼럼이 있는 Delta Sync 인덱스 | 연결된 Embeddings Databricks 노드 | query_vector로 보내는 임베딩된 검색 텍스트 |
모든 검색과 삽입되는 모든 문서마다 호출됨 |
Embeddings Databricks 노드에 대한 규칙은 위 표에서 그대로 따라옵니다.
- 모든 모드에서 Embeddings Databricks 노드를 Vector Store 노드에 연결하세요. 연결하지 않으면 노드는
A Embedding sub-node must be connected and enabled오류와 함께 실행을 거부합니다. - 관리형 인덱스에서는 Embeddings 노드가 호출되지 않습니다. Databricks가 쿼리를 직접 임베딩합니다.
- 자체 관리형 인덱스에서는 Embeddings 노드가 쿼리와 삽입되는 문서를 임베딩하므로, 인덱스의 벡터를 만든 모델과 차원을 그대로 선택하세요. 다른 모델을 선택하면 검색에서는
query vector dimension <n> does not match index vector dimension <m>오류로, 삽입에서는Databricks rejected the upsert into <index>. Failed primary keys: ...오류로 실패합니다.
노드 설정#
- 워크플로에 노드를 추가합니다. **Retrieve Documents (As Tool for AI Agent)**의 경우, 대신 AI Agent 또는 Databricks AI Agent 노드의 Tool 커넥터에서 **+**를 선택합니다. **Retrieve Documents (As Vector Store for Chain/Tool)**의 경우, Vector Store Retriever 또는 Vector Store Question Answer Tool 노드의 Vector Store 커넥터에서 **+**를 선택합니다.
- Credential to connect with에서 Databricks OAuth2 자격 증명을 선택하거나 새로 만듭니다.
- Operation Mode를 설정합니다. 모드별 필드는 노드 파라미터를 참조하세요.
- Index에서 인덱스를 선택합니다.
- From List: 노드는 자격 증명이 볼 수 있는 모든 Vector Search 엔드포인트의 모든 인덱스를
DELTA_SYNC - <endpoint>또는DIRECT_ACCESS - <endpoint>형태로 설명하여 나열합니다. 이름을 입력해 필터링할 수 있습니다. Insert Documents 모드에서는 목록에 Direct Access 인덱스만 표시됩니다. - Name: Unity Catalog 전체 이름인
catalog.schema.index를 입력합니다. 노드는 다른 형식을 거부하며, 편집기에서는Use the full name: catalog.schema.index, 표현식이 실행 시점에 이름을 만들어 내는 경우에는Invalid Databricks index "<name>": use catalog.schema.index오류가 표시됩니다.
- From List: 노드는 자격 증명이 볼 수 있는 모든 Vector Search 엔드포인트의 모든 인덱스를
- Content Column에서 문서 텍스트(
pageContent)가 될 칼럼을 선택합니다. 목록에는 기본 키와 벡터 칼럼을 제외한 인덱스의 칼럼이 표시됩니다. 관리형 인덱스에서는 임베딩 소스 칼럼이Embedding source column으로 표시되어 맨 앞에 오며, 필드를 비워 두면 이 칼럼을 사용합니다. 자체 관리형 인덱스에서는 칼럼을 반드시 선택해야 하며, 비워 두면Index <name> uses self-managed embeddings. Select a content column오류로 실패합니다. - Embedding 커넥터에서 **+**를 선택하고 Embeddings Databricks 노드를 추가합니다.
- 작업 모드의 필드와 필요한 옵션을 입력합니다.
노드 사용 패턴#
Databricks Vector Store 노드는 다음 패턴으로 사용할 수 있습니다.
일반 노드로 사용하여 문서 삽입 및 검색#
Databricks Vector Store 노드를 일반 노드로 사용하여 문서를 삽입하거나 가져올 수 있습니다. 이 패턴은 에이전트를 사용하지 않고 노드를 일반 연결 흐름에 배치합니다. 문서 로더로 Direct Access 인덱스를 채우려면 Insert Documents를 사용하고, 프롬프트로 검색을 실행하여 워크플로의 나머지 부분에서 결과를 다루려면 Get Many를 사용합니다.
도구로서 AI 에이전트에 직접 연결#
Databricks Vector Store 노드를 AI Agent 또는 Databricks AI Agent 노드의 도구 커넥터에 직접 연결하여, 질문에 답할 때 인덱스를 지식 소스로 사용할 수 있습니다. 에이전트가 직접 검색 쿼리를 작성하고, 도구는 일치하는 문서를 반환합니다.
이 경우 연결은 AI 에이전트(도구 커넥터) -> Databricks Vector Store 노드가 됩니다. 예제: AI 에이전트로 Databricks 인덱스에서 질문에 답변하기를 참조하세요.
리트리버를 사용하여 문서 가져오기#
Vector Store Retriever 노드를 Databricks Vector Store 노드와 함께 사용하여 인덱스에서 문서를 가져올 수 있습니다. 이 방식은 주어진 채팅 입력과 일치하는 문서를 벡터 스토어에서 가져오기 위해 Question and Answer Chain 노드와 함께 자주 사용됩니다.
연결 흐름은 Question and Answer Chain(Retriever 커넥터) -> Vector Store Retriever(Vector Store 커넥터) -> Databricks Vector Store가 됩니다.
Vector Store Question Answer Tool을 사용하여 질문에 답변#
또 다른 패턴은 Vector Store Question Answer Tool을 사용하여 Databricks Vector Store 노드의 결과를 요약하고 질문에 답하는 방식입니다. Databricks Vector Store를 도구로 직접 연결하는 대신, 벡터 스토어의 데이터를 요약하도록 특별히 설계된 도구를 사용합니다.
이 경우 연결 흐름은 다음과 같습니다. AI 에이전트(도구 커넥터) -> Vector Store Question Answer Tool(Vector Store 커넥터) -> Databricks Vector Store.
노드 파라미터#
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
이 노드에는 Update Documents 모드가 없습니다. 모든 모드는 노드 설정에서 설명한 Index 및 Content Column 필드와 아래 필드를 사용합니다.
Rerank Results#
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
Get Many 파라미터#
- Prompt: 검색 텍스트를 입력합니다. 관리형 인덱스에서는 노드가 이를
query_text로 보냅니다. 자체 관리형 인덱스에서는 Embeddings Databricks 노드가 먼저 이를 임베딩합니다. - Limit: 반환할 결과 수를 입력합니다. 기본값은
4입니다. 결과 수를 제어하는 유일한 설정입니다. 점수 임곗값 없음을 참조하세요. - Include Metadata: 출력에 문서 메타데이터를 포함할지 여부입니다. 기본적으로 켜져 있습니다.
각 출력 항목에는 { "document": { "pageContent": "...", "metadata": { ... } }, "score": 0.73 } 형태로 문서와 점수가 들어 있습니다. 점수는 인덱스나 검색 모드 간에 비교할 수 없습니다.
Insert Documents 파라미터#
- Index: Direct Access 인덱스입니다. 목록에는 Direct Access 인덱스만 표시됩니다. 이름으로 입력한 Delta Sync 인덱스는 쓰기 전에 실패합니다.
- Content Column: 문서 텍스트를 받는 칼럼입니다. 칼럼은 인덱스에 있어야 하며 기본 키나 벡터 칼럼일 수 없습니다. 노드는 잘못된 선택을 쓰기 전에 알려 줍니다. 예를 들어
Column id is the primary key of <index>. Select another Content Column또는Index <name> has no column <column>. Select a Content Column from: text, source와 같습니다. - Embedding Batch Size: 노드가 Embeddings Databricks 노드에 한 번의 요청으로 임베딩을 요청하는 문서 수입니다. 기본값은
200입니다.
Document 입력에 Default Data Loader 같은 문서 로더를 연결합니다. 노드는 연결된 Embeddings Databricks 노드로 문서를 임베딩하고 문서마다 행을 하나씩 씁니다. 삽입한 문서를 출력합니다. 행은 몇 초 안에 검색할 수 있게 됩니다.
노드가 행을 채우는 방식은 다음과 같습니다.
- 기본 키에는 임의의 UUID가 들어갑니다. 기본 제공 문서 로더는 문서 ID를 설정하지 않으므로, 같은 삽입을 두 번 실행하면 문서가 업데이트되지 않고 두 번 추가됩니다. 업스트림에서 중복을 제거하거나 Databricks에서 이전 행을 삭제하세요. LangChain Code 노드 등에서 만든 문서처럼 자체
id를 가진 문서는 해당 키로 기록되며, 같은 키를 가진 행을 대체합니다. - 인덱스의 칼럼과 일치하는 로더 메타데이터 키는 해당 칼럼에 들어갑니다. 노드는 일치하는 칼럼이 없는 키를 버립니다. 기본 키, 콘텐츠 칼럼, 벡터 칼럼을 가리키는 키도 버립니다. 버려진 키에 대한 경고는 없으며, 출력 항목에는 여전히 해당 키가 표시됩니다.
- 실행을 취소하면 삽입이 중단됩니다. 노드가 이미 기록한 행은 인덱스에 남습니다.
Retrieve Documents (As Vector Store for Chain/Tool) 파라미터#
이 모드에는 Index와 Content Column 외에 자체 필드가 없습니다. 연결된 리트리버나 도구가 가져올 문서 수를 제어하므로, Vector Store Retriever 또는 Vector Store Question Answer Tool 노드에서 Limit을 설정하세요. 여기에서 설정하는 노드 옵션은 해당 노드가 실행하는 모든 검색에 적용됩니다.
Retrieve Documents (As Tool for AI Agent) 파라미터#
- Description: 인덱스에 무엇이 들어 있고 언제 검색해야 하는지 에이전트에게 설명합니다.
Company handbook. Use it for any question about internal policies and processes.와 같이 구체적으로 설명하면 도구 호출이 더 안정적입니다. 에이전트는 노드 이름으로 도구를 인식합니다. - Limit: 도구 호출마다 반환할 문서 수를 입력합니다. 기본값은
4입니다. - Include Metadata: 도구 결과에 문서 메타데이터를 포함할지 여부입니다. 기본적으로 켜져 있습니다.
노드 옵션#
옵션은 세 가지 검색 모드인 Get Many, Retrieve Documents (As Vector Store for Chain/Tool), **Retrieve Documents (As Tool for AI Agent)**에 적용됩니다.
Metadata Columns#
문서 메타데이터로 반환할 칼럼입니다. 기본적으로 노드는 기본 키, 콘텐츠 칼럼, 벡터 칼럼을 제외한 인덱스의 모든 칼럼을 반환합니다. 에이전트가 읽는 페이로드를 작게 유지하려면 일부만 선택하세요. 목록에는 기본 키와 벡터 칼럼이 표시되지 않습니다.
Search Mode#
- Vector(기본값): 의미적 유사도만으로 결과의 순위를 매깁니다.
query_typeANN으로 전송됩니다. - Hybrid: 검색 텍스트에 대한 키워드 매칭을 추가하여, 제품 코드처럼 정확한 용어가 포함된 문서가 먼저 나옵니다.
query_typeHYBRID로 전송됩니다. 자체 관리형 인덱스에서는 노드가 벡터와 텍스트를 함께 보냅니다. 하이브리드 검색은 쿼리당 최대 200개의 결과를 반환합니다.
Metadata Filter#
인덱스 칼럼의 조건과 일치하는 행으로 결과를 제한하는 JSON 객체입니다. 노드는 이를 filters_json으로 보냅니다. 한 객체 안의 키는 AND로 결합됩니다. 키에는 칼럼 이름이 들어가며, 동등 비교가 아닌 경우에는 연산자도 함께 들어갑니다.
| 조건 | Metadata Filter |
|---|---|
| 값과 같음 | {"source": "handbook"} |
| 같지 않음 | {"source NOT": "draft"} |
비교(<, <=, >, >=) |
{"year >=": 2025} |
| 한 칼럼의 범위 | {"price >=": 30000, "price <=": 55000} |
| 여러 값 중 하나 | {"source": ["handbook", "faq"]} |
토큰 일치(% 와일드카드 없음) |
{"title LIKE": "pricing"} |
| 여러 칼럼(AND) | {"source": "handbook", "year >=": 2025} |
알아 둘 사항은 다음과 같습니다.
- 필터는 Standard Vector Search 엔드포인트에서만 동작합니다. Storage Optimized 엔드포인트는 SQL 필터 문자열을 요구하는데, 노드는 아직 이를 지원하지 않습니다. 필터를 설정하면 노드는 실행마다 한 번 엔드포인트 유형을 읽고, 엔드포인트가 Standard가 아니면 쿼리 전에 실패합니다.
Index <name> runs on endpoint <endpoint> of type STORAGE_OPTIMIZED. The Metadata Filter works on STANDARD endpoints only.필터가 없는 쿼리는 모든 엔드포인트 유형에서 동작합니다. - 엄격한 필터는 Limit보다 적은 행을 반환할 수 있습니다. Databricks가 가장 가까운 후보를 먼저 가져온 뒤 필터링하므로, 더 많은 일치 항목이 필요하면 Limit을 높이세요.
- 아무것도 일치하지 않는 필터는 오류 없이 항목 0개를 반환합니다. 잘못된 형식의 JSON은 요청 전에 Metadata Filter 필드를 지목하는 검증 오류로 실패합니다.
BETWEEN,LIKE의 와일드카드, JSON 칼럼에 중첩된 값에 대한 숫자 비교는 지원되지 않습니다. 전체 구문은 Databricks 필터링 가이드를 참조하세요.
알려진 제한 사항#
- Embeddings 입력은 항상 필요: Databricks가 쿼리를 임베딩하고 노드가 호출되지 않는 관리형 인덱스를 포함해, 모든 모드에 Embeddings Databricks 노드가 필요합니다.
- Insert Documents는 Direct Access 인덱스에서만 가능: Delta Sync 인덱스는 노드에서 읽기 전용입니다. 삽입 시 기본 키나 벡터 칼럼을 Content Column으로 지정하면 거부됩니다.
- 삽입된 행에는 임의의 키가 부여됩니다. 문서에 자체
id가 있는 경우는 예외입니다. 기본 제공 문서 로더는id를 설정하지 않으므로, 다시 실행하면 행이 업데이트되지 않고 중복됩니다. - Metadata Filter는 Standard 엔드포인트에서만 동작: Storage Optimized 엔드포인트는 노드가 아직 지원하지 않는 SQL 필터 문자열을 사용합니다. 해당 엔드포인트에서 필터를 사용한 쿼리는 실행 전에 실패합니다.
- 하이브리드 검색은 쿼리당 최대 200개의 결과를 반환합니다.
- 엄격한 필터는 Limit보다 적은 행을 반환할 수 있습니다. Databricks가 가장 가까운 후보를 가져온 뒤 필터링하기 때문입니다.
- 토큰당 과금 방식의 속도 제한: 많은 문서를 한 번에 임베딩하면 임베딩 모델 서비스의 워크스페이스 속도 제한에 걸릴 수 있습니다. 이를 피하는 방법은 Embeddings Databricks 페이지의 속도 제한을 참조하세요.
점수 임곗값 없음#
이 노드에는 의도적으로 점수 임곗값 필드가 없습니다. Vector 검색과 Hybrid 검색은 점수 척도가 다릅니다. 자체 관리형 인덱스의 유사도 점수는 0.003 근처일 수 있지만, Hybrid 검색은 정확한 키워드 일치에 1.0을 매깁니다. 하나의 기준선으로는 두 경우를 모두 맞출 수 없으며, 잘못된 기준선은 흔적 없이 모든 결과를 버리게 됩니다. 결과 수는 Limit으로 제어하고, 특정 인덱스에 기준선이 필요하면 이후 노드에서 score 필드를 기준으로 필터링하세요.
예제: AI 에이전트로 Databricks 인덱스에서 질문에 답변하기#
이 워크플로는 Databricks가 임베딩을 계산하는 Delta Sync 인덱스에 저장된 사내 핸드북으로 채팅 질문에 답변합니다. 인덱스 이름과 모델 이름은 사용자의 것으로 바꾸세요.
- Databricks에서 핸드북 테이블에 대한 Delta Sync 인덱스를 만듭니다. 예를 들어
main.docs.handbook_index로 하고, 임베딩 소스로content칼럼을, 문서 출처로source칼럼을 둡니다. 벡터 검색 인덱스 생성 및 쿼리를 참조하세요. - Chat Trigger 노드를 추가합니다.
- 그 뒤에 Databricks AI Agent 노드를 추가합니다. AI Agent 노드도 트레이스 내보내기만 없을 뿐 동일하게 동작합니다. Options에서
Answer questions about the company handbook with the handbook tool. Say so when the handbook doesn't cover a question.과 같은 System Message를 설정합니다. - 에이전트의 Chat Model 커넥터에서 **+**를 선택하고 Databricks Chat Model 노드를 추가합니다. Databricks 자격 증명과 채팅을 지원하는 모델 서비스를 선택합니다. 예를 들어
system.ai.meta-llama-3-3-70b-instruct입니다. - Memory 커넥터에서 **+**를 선택하고 Simple Memory 노드를 추가하여, 후속 질문이 컨텍스트를 유지하도록 합니다.
- Tool 커넥터에서 **+**를 선택하고 Databricks Vector Store 노드를 추가합니다. 노드 이름을
handbook으로 지정합니다. Operation Mode를 **Retrieve Documents (As Tool for AI Agent)**로 설정하고, Index에서main.docs.handbook_index를 선택하고, 노드가 임베딩 소스 칼럼을 사용하도록 Content Column은 비워 두고, Description을Company handbook. Use it for any question about internal policies and processes.로 설정합니다. Limit은4로 유지합니다. - 벡터 스토어의 Embedding 커넥터에서 **+**를 선택하고, 같은 자격 증명과 임베딩 모델 서비스(예:
system.ai.gte-large-en)를 사용하는 Embeddings Databricks 노드를 추가합니다. 인덱스가 관리형이므로 Databricks가 쿼리를 임베딩하고 이 노드는 호출되지 않지만, 노드에는 연결이 필요합니다. - 선택 사항으로, 에이전트 노드에서 Databricks 자격 증명을 선택하고 Export Traces to MLflow를 켜면 핸드북 검색을 포함한 각 실행을 MLflow Tracing에서 확인할 수 있습니다.
- 채팅을 열고 핸드북에 답이 있는 질문을 합니다. 실행 내역에는 에이전트의 검색 쿼리와 반환된 문서가 포함된
handbook도구 호출이 한 번 표시됩니다.
자체 관리형 인덱스를 대신 검색하려면, 벡터 스토어 노드에서 Content Column을 설정하고 Embeddings Databricks 노드에서 인덱스의 벡터를 만든 모델을 선택하세요. 에이전트를 인덱스의 일부로 제한하려면 벡터 스토어 노드의 옵션에 {"source": "handbook"}와 같은 Metadata Filter를 추가하세요.
관련 리소스#
- 커뮤니티 패키지에서 마이그레이션
- Databricks 자격 증명
- Embeddings Databricks
- Databricks AI Agent
- Databricks Chat Model
- 인덱스 생성 및 목록 조회 같은 Vector Search 인덱스 작업을 위한 Databricks 노드
- Vector Store Retriever 및 Vector Store Question Answer Tool
- Databricks 문서의 Databricks Vector Search, Query index API, 필터링 가이드
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
일반적인 문제#
A Embedding sub-node must be connected and enabled#
노드의 Embedding 입력에 Embeddings Databricks 노드가 없습니다. 노드가 호출되지 않는 관리형 인덱스를 포함해 모든 모드에서 하나를 연결하세요.
Index uses self-managed embeddings#
Index <name> uses self-managed embeddings. Select a content column 오류는 인덱스가 자체 벡터를 가지고 있어서 노드가 어느 칼럼에 텍스트가 있는지 추론할 수 없다는 뜻입니다. Content Column에서 칼럼을 선택하세요.
Index syncs from its source table#
Insert Documents가 Delta Sync 인덱스를 대상으로 하면 노드는 Index <name> syncs from its source table. Use a Direct Access index to insert documents 오류를 보고합니다. Databricks는 Delta Sync 인덱스를 소스 테이블에서 채우므로, 대신 테이블에 행을 추가하거나 Direct Access 인덱스에 삽입하세요.
Insufficient permissions for UC entity#
Databricks Vector Search request failed (403): Insufficient permissions for UC entity <index> 오류는 자격 증명의 ID에 인덱스의 SELECT 권한이 없거나, 삽입의 경우 MODIFY 권한이 없다는 뜻입니다. Unity Catalog에서 USE CATALOG 및 USE SCHEMA와 함께 해당 권한을 부여하세요.
Unity Catalog entity doesn't exist#
Databricks Vector Search request failed (404): Unity Catalog entity <name> does not exist 오류는 Index 이름이 ID가 볼 수 있는 인덱스와 일치하지 않는다는 뜻입니다. 세 부분으로 된 이름을 확인하거나, From List에서 인덱스를 선택하세요.
Query vector dimension doesn't match the index#
query vector dimension <n> does not match index vector dimension <m> 오류는 Embeddings Databricks 노드가 인덱스와 차원이 다른 모델을 사용한다는 뜻입니다. 인덱스의 벡터를 만든 모델을 선택하세요. 삽입에서는 같은 불일치가 Databricks rejected the upsert into <index>. Failed primary keys: ... 오류로 나타나며, 노드는 아무것도 기록하지 않습니다.
Failed to retrieve Databricks access token#
자격 증명이 워크스페이스에서 토큰을 가져올 수 없습니다. 서비스 주체를 사용하는 경우 invalid_client는 주체가 워크스페이스에 할당되지 않았다는 뜻이므로, Workspace access 권한(entitlement)과 함께 추가하세요. 오류 설명에 HTML이 표시되면 자격 증명의 Host가 Databricks 워크스페이스 URL이 아닙니다.
Host must use HTTPS#
자격 증명의 Host가 https:// URL이 아니면, 예를 들어 http://로 시작하거나 스킴이 없으면 노드는 Databricks host must use https 오류로 실패합니다. 모든 요청에는 토큰이 포함되므로 노드는 일반 HTTP를 거부합니다. https://를 포함한 전체 워크스페이스 URL을 입력하세요.
Rate limit reached during an insert#
임베딩 모델 서비스가 REQUEST_LIMIT_EXCEEDED로 배치를 거부했습니다. 노드는 제한에 걸린 청크를 기록하지 않았지만, 그 이전에 기록한 청크는 인덱스에 남아 있으므로 다시 시도하기 전에 인덱스를 확인하세요. Embeddings Databricks 페이지의 속도 제한을 참조하세요.
The Metadata Filter works on STANDARD endpoints only#
Metadata Filter가 설정되어 있고 인덱스가 Storage Optimized 엔드포인트에서 실행 중입니다. 이 엔드포인트는 노드가 아직 지원하지 않는 SQL 필터 문자열을 사용합니다. 필터를 제거하거나 인덱스를 Standard 엔드포인트로 옮기세요. 메시지가 Could not read the type of the endpoint로 시작하면 자격 증명의 ID가 Vector Search 엔드포인트를 읽을 수 없는 것이므로, 엔드포인트에 대한 읽기 권한을 부여하거나 필터를 제거하세요.
Footnotes
-
AI 체인을 사용하면 대규모 언어 모델(LLM) 및 기타 리소스와 일련의 컴포넌트 호출을 통해 상호작용할 수 있습니다. n8n의 AI 체인은 영구 메모리를 사용하지 않으므로, 이를 사용하여 이전 컨텍스트를 참조할 수는 없습니다(이를 위해서는 AI 에이전트를 사용하세요). ↩
-
AI 컨텍스트에서 도구란 요청에 응답할 때 AI가 특정 정보나 기능을 참조할 수 있는 부가 리소스입니다. AI 모델은 도구를 사용하여 외부 시스템과 상호작용하거나 특정한 집중 작업을 완료할 수 있습니다. ↩
-
AI 에이전트는 요청에 응답하고, 결정을 내리고, 사용자를 위해 실제 작업을 수행할 수 있는 인공지능 시스템입니다. 대규모 언어 모델(LLM)을 사용하여 사용자 입력을 해석하고, 사용 가능한 정보와 리소스를 활용해 요청을 가장 잘 처리하는 방법을 결정합니다. ↩