DBAPI를 통한 Milvus 벡터 데이터베이스 접속: HTTP 실행기 파라미터 매핑 실전
Milvus란?
Milvus는 AI 애플리케이션을 위해 설계된 오픈소스 벡터 데이터베이스로, 대량의 벡터 데이터 저장, 인덱싱 및 유사도 검색을 지원합니다. RAG(검색 증강 생성), 시맨틱 검색, 추천 시스템 등 다양한 분야에서 널리 사용되고 있습니다.
Milvus는 완전한 RESTful API 인터페이스를 제공하며, HTTP 프로토콜을 통해 벡터 데이터의 삽입, 조회, 검색 등의 작업을 수행할 수 있습니다.
왜 DBAPI를 이용해 Milvus에 접속하나요?
Milvus의 HTTP API를 직접 호출하려면 요청 주소를 수동으로 구성하고, 요청 파라미터를 작성하며, 인증과 권한 부여를 처리해야 합니다. DBAPI의 HTTP 실행기를 통해 Milvus에 접속하면 다음과 같은 이점이 있습니다:
- 통합 API 관리: 모든 Milvus 작업이 DBAPI API 형태로 일원화되어 권한 관리, 트래픽 제어, 모니터링 기능을 바로 사용할 수 있습니다.
- 파라미터 매핑 간소화: 사용자 정의 매핑 모드를 통해 비즈니스 파라미터를 Milvus가 요구하는 요청 본문 형식으로 자동 변환되므로, 호출 측에서는 Milvus 인터페이스의 세부 사항을 신경 쓸 필요가 없습니다.
- 보안 관리: DBAPI의 Token 인증 및 IP 방화벽 기능을 그대로 활용할 수 있습니다.
- 무코드 연동: 별도의 통합 코드 작성 없이 단순히 설정만으로 연동이 가능합니다.
핵심 기능: HTTP 실행기의 파라미터 사용자 정의 매핑
DBAPI 엔터프라이즈 에디션 4.5.0 버전부터 HTTP 실행기의 사용자 정의 매핑 모드가 강화되었습니다. JSON 템플릿과 ${} 자리표시자 및 Groovy 표현식을 조합하여, 호출 측에서 전달된 파라미터를 목표 인터페이스가 요구하는 요청 본문 형식으로 유연하게 매핑할 수 있습니다.
호출 측 전달: { "collection": "my_collection", "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }
│ HTTP 실행기 파라미터 매핑
▼
Milvus 수신: { "collectionName": "my_collection", "data": [{ "id": 1, "vector": [0.1, 0.2, ...], "text": "xxx" }] }실전: Milvus 연동
사전 준비 사항
- DBAPI 엔터프라이즈 에디션 4.5.0 이상 버전
- 이미 배포된 Milvus 서비스 (본 문서에서는 Milvus HTTP API v2를 예로 설명)
- Milvus 내에 미리 생성된 컬렉션(Collection)
첫 번째 단계: HTTP 데이터 소스 생성
DBAPI 관리 백엔드에서 데이터 소스 관리로 이동한 후, 새 데이터 소스 생성 버튼을 클릭합니다.
| 설정 항목 | 값 |
|---|---|
| 이름 | Milvus 서비스 |
| 유형 | HTTP |
| 주소 | http://192.168.1.100:19530 |
주소는 Milvus 서비스의 HTTP 포트이며, 기본값은 19530입니다.
두 번째 단계: 벡터 삽입 API 생성
대상 그룹 내에서 HTTP 실행기를 사용하여 API를 생성합니다.
기본 정보
| 설정 항목 | 값 |
|---|---|
| API 이름 | Milvus 벡터 삽입 |
| API 경로 | /milvus/insert |
| 접근 권한 | private |
| 요청 파라미터 | id(bigint), vector(string), text(string) |
vector파라미터는[0.1, 0.2, ...]와 같은 JSON 문자열로 전달됩니다.
실행기 설정
| 설정 항목 | 값 |
|---|---|
| 실행기 유형 | HTTP 인터페이스 프록시 실행기 |
| 데이터 소스 | Milvus 서비스 |
| 메서드 | POST |
| URL 경로 | /v2/vectordb/entities/insert |
| Content-Type | application/json |
| 파라미터 전달 모드 | 사용자 정의 매핑 |
사용자 정의 요청 헤더:
| 키 | 값 |
|---|---|
Authorization | YOUR_MILVUS_TOKEN |
Milvus가 인증을 활성화한 경우, 사용자 정의 요청 헤더에 Token을 설정하면 HTTP 실행기가 이를 자동으로 전달합니다.
요청 본문 템플릿:
{"collectionName": "news_articles", "data": [{"id": ${_parameters.id}, "vector": ${_parameters.vector}, "text": ${_parameters.text}}]}
collectionName은 템플릿에 미리 정의되어 있으므로 호출 측에서 별도로 전달할 필요가 없습니다.vector파라미터는 JSON 배열 문자열로 전달되며, Milvus의vector필드로 매핑됩니다.
호출 결과
호출 측에서 다음과 같은 요청을 보냅니다:
POST https://127.0.0.1:8520/milvus/insert
Content-Type: application/json
{
"id": 1001,
"vector": [0.352, 0.187, 0.921, 0.453, 0.672],
"text": "DBAPI를 통한 벡터 데이터베이스 연동"
}시스템은 템플릿에 따라 매핑된 후 Milvus로 전달합니다(자동으로 사용자 정의 요청 헤더가 추가됨):
POST http://192.168.1.100:19530/v2/vectordb/entities/insert
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "data": [{"id": 1001, "vector": [0.352, 0.187, 0.921, 0.453, 0.672], "text": "DBAPI를 통한 벡터 데이터베이스 연동"}]}세 번째 단계: 벡터 검색 API 생성
기본 정보
| 설정 항목 | 값 |
|---|---|
| API 이름 | Milvus 벡터 검색 |
| API 경로 | /milvus/search |
| 접근 권한 | private |
| 요청 파라미터 | vector(string), limit(bigint) |
실행기 설정
| 설정 항목 | 값 |
|---|---|
| 실행기 유형 | HTTP 인터페이스 프록시 실행기 |
| 데이터 소스 | Milvus 서비스 |
| 메서드 | POST |
| URL 경로 | /v2/vectordb/entities/search |
| Content-Type | application/json |
| 파라미터 전달 모드 | 사용자 정의 매핑 |
요청 본문 템플릿:
{"collectionName": "news_articles", "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "outputFields": ["id", "text", "vector"]}
collectionName은 템플릿에 미리 정의되어 있으므로 호출 측에서 별도로 전달할 필요가 없습니다.
호출 결과
호출 측에서 다음과 같은 요청을 보냅니다:
POST https://127.0.0.1:8520/milvus/search
Content-Type: application/json
{
"vector": [0.350, 0.190, 0.910, 0.450, 0.670],
"limit": 5
}시스템은 매핑 후 Milvus로 전달합니다:
POST http://192.168.1.100:19530/v2/vectordb/entities/search
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "vector": [0.350, 0.190, 0.910, 0.450, 0.670], "limit": 5, "outputFields": ["id", "text", "vector"]}네 번째 단계: ID 기반 조회 API 생성
기본 정보
| 설정 항목 | 값 |
|---|---|
| API 이름 | Milvus 벡터 조회 |
| API 경로 | /milvus/query |
| 접근 권한 | private |
| 요청 파라미터 | collection(string), id(bigint) |
실행기 설정
| 설정 항목 | 값 |
|---|---|
| 실행기 유형 | HTTP 인터페이스 프록시 실행기 |
| 데이터 소스 | Milvus 서비스 |
| 메서드 | POST |
| URL 경로 | /v2/vectordb/entities/query |
| Content-Type | application/json |
| 파라미터 전달 모드 | 사용자 정의 매핑 |
요청 본문 템플릿:
{"collectionName": "news_articles", "filter": "id == " + ${_parameters.id}, "outputFields": ["id", "text", "vector"]}Groovy 표현식을 통해
id == 1001과 같은 필터 조건을 동적으로 생성하므로, 호출 측에서는 Milvus의 쿼리 문법을 이해할 필요가 없습니다.
호출 결과
호출 측에서 다음과 같은 요청을 보냅니다:
POST https://127.0.0.1:8520/milvus/query
Content-Type: application/json
{
"id": 1001
}시스템은 매핑 후 Milvus로 전달합니다:
POST http://192.168.1.100:19530/v2/vectordb/entities/query
Content-Type: application/json
Authorization: YOUR_MILVUS_TOKEN
{"collectionName": "news_articles", "filter": "id == 1001", "outputFields": ["id", "text", "vector"]}추가 파라미터 매핑 팁
복잡한 중첩 구조
Milvus 컬렉션에 여러 개의 벡터 필드나 중첩된 필드가 있는 경우에도 템플릿을 통해 유연하게 구성할 수 있습니다:
{"collectionName": ${_parameters.collection}, "data": [{"id": ${_parameters.id}, "titleVector": ${_parameters.titleVector}, "contentVector": ${_parameters.contentVector}, "metadata": {"author": ${_parameters.author}, "tags": ${_parameters.tags}}}]}파라미터 연산
전달된 파라미터에 대해 사전 처리를 적용할 수 있습니다:
{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit + 10}, "offset": ${(_parameters.page - 1) * _parameters.pageSize}}조건부 할당
파라미터 값에 따라 검색 조건을 동적으로 설정할 수 있습니다:
{"collectionName": ${_parameters.collection}, "vector": ${_parameters.vector}, "limit": ${_parameters.limit}, "params": {"nprobe": ${_parameters.precision == "high" ? 64 : 16}}}요약
DBAPI HTTP 실행기의 파라미터 사용자 정의 매핑 기능을 통해 Milvus 벡터 데이터베이스 연동이 매우 간편해집니다:
- 호출 측에서는 비즈니스 의미를 담은 파라미터만 전달하면 되므로 Milvus API의 세부 사항을 알 필요가 없습니다.
- 파라미터 매핑 템플릿은 중앙에서 관리되므로, Milvus 인터페이스가 변경되더라도 호출 측에는 영향을 미치지 않습니다.
- 인터페이스는 DBAPI의 인증, 트래픽 제어, 모니터링 등 엔터프라이즈급 기능을 그대로 활용할 수 있습니다.
- 완전 무코드로, 설정만으로 연동이 가능합니다.
버전 요구사항: DBAPI 엔터프라이즈 에디션 4.5.0 이상 버전에서 HTTP 실행기의 파라미터 사용자 정의 매핑 기능을 지원합니다.