Embeddings Databricks 노드
n8n v2.47요약
Embeddings Databricks 노드를 사용하면 Databricks 워크스페이스에서 제공하는 임베딩 모델로 텍스트의 임베딩1을 생성할 수 있습니다. 이 페이지에서는 Embeddings Databricks 노드의 사전 요구 사항, 설정 단계, 연결 규칙, 노드 파라미터, 알려진 문제를 확인할 수 있습니다.
Embeddings Databricks 노드를 사용하면 Databricks 워크스페이스에서 제공하는 임베딩 모델로 텍스트의 임베딩1을 생성할 수 있습니다. 이 노드는 Databricks Chat Model 노드가 사용하는 것과 같은 게이트웨이인 Unity AI Gateway 모델 서비스를 호출합니다. 주된 용도는 모든 작업 모드에서 임베딩 연결이 필요한 Databricks Vector Store 노드와 함께 사용하는 것입니다.
이 페이지에서는 Embeddings Databricks 노드의 사전 요구 사항, 설정 단계, 연결 규칙, 노드 파라미터, 알려진 문제를 확인할 수 있습니다.
자격 증명
인증 설정 방법은 Databricks 자격 증명을 참조하세요. 이 노드는 서비스 프린시펄 또는 사용자 로그인 방식의 Databricks OAuth2 API 자격 증명만 허용합니다. 개인 액세스 토큰은 허용하지 않습니다.
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
사전 요구 사항#
- Unity AI Gateway가 활성화된 Databricks 워크스페이스.
- 서비스 프린시펄 또는 사용자 로그인을 사용하는, n8n의 Databricks OAuth2 자격 증명.
- 자격 증명이 인증에 사용하는 ID에는 모델 서비스가 있는 카탈로그와 스키마에 대한 USE CATALOG, USE SCHEMA 권한과 모델 서비스에 대한 EXECUTE 권한이 필요합니다. Databricks는
system.ai모델 서비스의 EXECUTE 권한을 기본적으로 모든 워크스페이스 사용자에게 부여합니다. 필요한 Databricks 권한을 참조하세요.
노드 설정#
- 워크플로에 Databricks Vector Store 노드 또는 임베딩 서브 노드를 받는 다른 노드를 추가합니다.
- 노드의 Embedding 커넥터에서 **+**를 선택한 다음 Embeddings Databricks를 선택합니다.
- Credential to connect with에서 기존 Databricks OAuth2 자격 증명을 선택하거나 새로 생성합니다.
- Model에서 목록을 열어 모델 서비스를 선택합니다. n8n은 자격 증명이 접근할 수 있는 모델 서비스 중 임베딩을 지원하는 서비스를 불러오며, 채팅 모델은 제외합니다. 입력하여 목록을 필터링할 수 있습니다. 목록에 없는 서비스를 사용하려면 ID로 전환하고 전체 이름을 입력하세요(예:
system.ai.gte-large-en).
노드를 Databricks 인덱스와 연결#
어떤 모델을 선택할지는 Databricks Vector Store 노드가 사용하는 인덱스에 따라 달라집니다.
- Managed 인덱스(Databricks 임베딩 모델을 사용하는 Delta Sync 인덱스): Databricks가 인덱스 자체 모델로 쿼리를 직접 임베딩합니다. Embeddings Databricks 노드는 연결되어 있어야 하지만 호출되지 않으므로 어떤 모델 서비스든 사용할 수 있습니다.
- Self-managed 인덱스(Direct Access 인덱스 또는 자체 벡터 칼럼이 있는 Delta Sync 인덱스): Embeddings Databricks 노드가 모든 검색 쿼리를 임베딩하며, Direct Access 인덱스에서는 삽입되는 모든 문서도 임베딩합니다. 인덱스를 만들 때 사용한 모델과 차원을 선택하세요. 1024차원인
databricks-gte-large-en으로 만든 인덱스에는system.ai.gte-large-en모델 서비스가 필요합니다. 다른 모델을 사용하면 검색 시query vector dimension <n> does not match index vector dimension <m>오류로, 삽입 시Databricks rejected the upsert into <index>. Failed primary keys: ...오류로 실패합니다.
벡터 저장소 노드가 어떤 쿼리 형식을 보낼지 결정하는 방식은 Databricks Vector Store 페이지의 인덱스 유형과 임베딩을 참조하세요.
이 노드는 표준 임베딩 서브 노드이므로 Simple Vector Store와 같은 n8n의 다른 벡터 저장소 노드에서도 작동합니다.
노드 파라미터#
- Model: 임베딩을 생성하는 Unity AI Gateway 모델 서비스이며,
catalog.schema.service형식의 이름을 사용합니다.- From List: 자격 증명이 접근할 수 있는 모델 서비스 중 임베딩을 지원하는 서비스에서 선택합니다.
- ID: 모델 서비스의 전체 이름을 직접 입력합니다. 임베딩을 지원하지만 임베딩 가능 서비스로 표시되지 않는 서비스에 사용하세요.
노드 옵션#
- Batch Size: 한 요청으로 보낼 최대 문서 수입니다. 기본값은
512, 최댓값은2048입니다. 값을 낮추기 전에 속도 제한을 참조하세요. - Strip New Lines: 임베딩하기 전에 입력 텍스트에서 줄바꿈 문자를 제거할지 여부입니다. 기본적으로 켜져 있습니다.
- Timeout: 요청에 허용되는 최대 시간(밀리초)입니다. 기본값은
360000(6분)입니다. 시간 안에 끝나지 않은 요청은Request timed out.오류로 실패합니다. - Max Retries: 실패한 요청을 다시 시도할 횟수입니다. 기본값은
2입니다.
속도 제한#
토큰 단위 종량제 모델 서비스에는 워크스페이스별 속도 제한이 적용됩니다. Databricks Vector Store 노드가 문서를 삽입할 때는 Embedding Batch Size(기본값 200) 크기의 청크로 임베딩하고, 각 청크는 이 노드의 Batch Size 단위 요청으로 나뉘어 병렬로 전송됩니다. Batch Size가 작으면 청크 하나가 동시에 많은 요청으로 바뀌어 모델 서비스의 워크스페이스 제한을 초과할 수 있습니다. 노드는 거부된 요청을 백오프와 함께 Max Retries까지 재시도하고, 그래도 실패하면 삽입이 Databricks rate limit reached for <service>: REQUEST_LIMIT_EXCEEDED: Exceeded workspace QPS rate limit 오류로 실패합니다. 노드는 제한에 걸린 청크를 기록하지 않지만, 그 이전에 임베딩하여 기록한 청크는 인덱스에 남아 있으므로 다시 시도하기 전에 인덱스를 확인하세요.
이를 피하려면 청크가 한 번의 요청으로 전송되도록 Batch Size를 기본값으로 유지하고, 동시 삽입 수를 낮게 유지하거나, 모델에 프로비저닝된 처리량 엔드포인트를 사용하세요.
관련 리소스#
- Databricks Vector Store
- Databricks AI Agent
- Databricks Chat Model
- Databricks 자격 증명
- Databricks 문서의 Unity AI Gateway 모델 서비스
- 커뮤니티 패키지에서 마이그레이션하기: n8n-nodes-databricks 커뮤니티 패키지에서 마이그레이션을 참조하세요
이 섹션의 상세 내용은 n8n 공식 문서를 참조하세요.
자주 발생하는 문제#
모델 서비스를 찾을 수 없음#
모델 목록이 비어 있고 노드가 No model services found를 보고합니다. 워크스페이스에서 Unity AI Gateway가 활성화되지 않았거나, 자격 증명의 ID가 어떤 모델 서비스에도 접근할 수 없는 경우입니다. 워크스페이스 설정을 확인한 다음, 하나 이상의 모델 서비스에 대해 USE CATALOG, USE SCHEMA, EXECUTE 권한을 부여하세요.
임베딩을 지원하는 모델 서비스를 찾을 수 없음#
자격 증명이 모델 서비스를 볼 수는 있지만 임베딩을 지원한다고 표시된 서비스가 없는 경우입니다. Model을 ID로 전환하고 서비스 이름을 직접 입력하세요. 채팅 전용 서비스는 이 노드에서 작동하지 않습니다.
모델 서비스가 존재하지 않음#
노드가 The resource you are requesting could not be found 오류로 실패하며, 오류 설명에 존재하지 않는 서비스 이름이 표시됩니다. Model 이름이 워크스페이스에 없는 경우입니다. 세 부분으로 된 이름을 확인하거나 From List에서 서비스를 선택하세요.
쿼리 벡터 차원이 인덱스와 일치하지 않음#
모델이 Databricks Vector Store 노드가 검색하는 인덱스와 맞지 않는 경우입니다. 노드를 Databricks 인덱스와 연결을 참조하세요.
속도 제한 도달#
실행이 Databricks rate limit reached for <service> 메시지와 429 상태로 실패합니다. 속도 제한을 참조하세요.
호스트는 HTTPS를 사용해야 함#
자격 증명의 Host가 https:// URL이 아니면(예: http://로 시작하거나 스킴이 없는 경우) 노드가 Databricks host must use https 오류로 실패합니다. 모든 요청에 토큰이 포함되므로 노드는 일반 HTTP를 거부합니다. https://를 포함한 전체 워크스페이스 URL을 입력하세요.
연결 오류#
노드가 Databricks 메시지 없이 Connection error.를 보고합니다. 자격 증명의 Host가 Databricks 워크스페이스를 가리키지 않거나, n8n 인스턴스에서 워크스페이스에 접근할 수 없는 경우입니다. 호스트 URL과 네트워크 경로를 확인하세요.
Footnotes
-
임베딩은 벡터를 사용해 데이터를 수치로 표현한 것입니다. AI는 여러 차원에 걸쳐 값을 매핑하여 복잡한 데이터와 관계를 해석하는 데 임베딩을 사용합니다. 벡터 데이터베이스(벡터 저장소)는 임베딩을 저장하고 조회하도록 설계된 데이터베이스입니다. ↩