Milvus 연결

Milvus는 대용량 벡터 검색에 쓰는 외부 벡터 DB입니다. 이미 조직에서 Milvus를 운영하고 있거나, 검색 데이터가 매우 많아 별도 클러스터로 관리하려는 경우에 사용합니다.

Milvus를 쓰더라도 원본 파일과 문서 텍스트는 SpaceBuilder에 그대로 남습니다. Milvus에는 검색에 필요한 벡터와 최소한의 정보만 저장됩니다.

Milvus 설치

SpaceBuilder는 Milvus 2.4 이상의 REST API(v2, 기본 포트 19530)를 사용합니다. 모든 요청을 /v2/vectordb/... 경로로 보내므로 Milvus 2.3 이하에서는 동작하지 않습니다. SpaceBuilder 서버에서 이 포트로 접속할 수 있는 Milvus가 필요합니다. 이미 운영 중인 Milvus가 있다면 이 절은 건너뛰고 컬렉션 미리 만들기로 가세요.

Milvus는 단일 서버용 Standalone과 대규모 클러스터용 Distributed 두 가지 방식이 있습니다. SpaceBuilder 연결에는 Standalone이면 충분합니다.

준비

실행

Milvus가 제공하는 설치 스크립트를 사용하면 필요한 구성 요소가 포함된 컨테이너 하나로 실행됩니다.

mkdir -p ~/milvus && cd ~/milvus
curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh
bash standalone_embed.sh start

• 데이터는 스크립트를 실행한 폴더 아래 volumes/milvus에 저장됩니다. 이 폴더를 지우면 데이터가 사라집니다.
• 멈추거나 다시 시작할 때는 같은 폴더에서 bash standalone_embed.sh stop / bash standalone_embed.sh start를 실행합니다.
• 설정을 바꿀 때는 같은 폴더에 생성된 user.yaml을 수정하고 다시 시작합니다.

인증 켜기

SpaceBuilder와 다른 서버에서 운영하거나 여러 사람이 접근할 수 있는 네트워크라면 인증을 켜세요. user.yaml에 아래를 추가하고 다시 시작합니다.

common:
  security:
    authorizationEnabled: true

인증을 켜면 기본 계정 root / 비밀번호 Milvus로 접속할 수 있습니다. 기본 비밀번호는 반드시 바꾸고, SpaceBuilder 전용 계정을 따로 만드는 것을 권장합니다. SpaceBuilder 연결 설정에는 API 키(토큰, 사용자명:비밀번호 형식) 또는 사용자 이름과 비밀번호를 입력할 수 있습니다. 둘 다 입력하면 API 키를 사용합니다.

설치 확인

curl http://localhost:9091/healthz

OK가 오면 정상입니다. 브라우저에서 http://<Milvus 서버 주소>:9091/webui/를 열면 컬렉션과 상태를 볼 수 있는 관리 화면이 나옵니다(Milvus 2.5 이상).

운영 팁

• 방화벽: SpaceBuilder 서버만 19530 포트에 접속할 수 있게 제한하세요. 9091은 외부에 열지 마세요.
• 백업: 벡터는 원본에서 다시 만들 수 있는 파생 데이터입니다. 별도 백업 없이도 SpaceBuilder에서 전체 데이터 다시 인덱싱으로 복구할 수 있습니다.
• 업데이트: Milvus 버전을 올릴 때는 Milvus 공식 업그레이드 안내를 따르세요. 마이너 버전이 달라지면 데이터 마이그레이션이 필요할 수 있습니다.

컬렉션 미리 만들기

Qdrant와 달리 Milvus 컬렉션은 자동으로 만들어지지 않습니다. 연결 설정을 저장하기 전에 아래 구조로 컬렉션을 먼저 만들어야 합니다.

• vector 필드의 차원(dim)은 SpaceBuilder에 설정할 벡터 차원과 같아야 합니다. (bge-m3는 1024)
• vector 필드의 인덱스 거리 계산 방식(metric)은 COSINE이어야 합니다.
• SpaceBuilder는 text를 4,096자에서 잘라 저장합니다. UTF-8에서 한글은 글자당 3바이트, 이모지는 4바이트이므로 max_length를 16384(4,096자 × 4바이트) 이상으로 잡으면 어떤 문서 조각도 길이 제한에 걸리지 않습니다.
• source_path는 파일 경로가 길고 한글이 섞일 수 있으므로 4096 정도로 넉넉하게 잡으세요.

아래는 Milvus REST API(v2)로 컬렉션을 만드는 명령입니다. <Milvus 서버 주소>, 인증 정보, 컬렉션 이름, dim 값은 환경에 맞게 바꾸세요.

• Authorization에는 <사용자명>:<비밀번호>를 넣거나, 그 자리에 API 키(토큰)를 넣습니다.
• 인증을 켜지 않았다면 Authorization 줄을 지우세요.

curl -X POST "http://<Milvus 서버 주소>:19530/v2/vectordb/collections/create" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <사용자명>:<비밀번호>" \
  -d '{
    "collectionName": "setfn_knowledge_example",
    "schema": {
      "autoId": false,
      "enableDynamicField": false,
      "fields": [
        { "fieldName": "id", "dataType": "VarChar", "isPrimary": true, "elementTypeParams": { "max_length": 64 } },
        { "fieldName": "instance_namespace", "dataType": "VarChar", "elementTypeParams": { "max_length": 64 } },
        { "fieldName": "generation_id", "dataType": "VarChar", "elementTypeParams": { "max_length": 64 } },
        { "fieldName": "chunk_id", "dataType": "Int64" },
        { "fieldName": "space_flag", "dataType": "VarChar", "elementTypeParams": { "max_length": 16 } },
        { "fieldName": "owner_id", "dataType": "VarChar", "elementTypeParams": { "max_length": 64 } },
        { "fieldName": "source_path", "dataType": "VarChar", "elementTypeParams": { "max_length": 4096 } },
        { "fieldName": "text", "dataType": "VarChar", "elementTypeParams": { "max_length": 16384 } },
        { "fieldName": "vector", "dataType": "FloatVector", "elementTypeParams": { "dim": 1024 } }
      ]
    },
    "indexParams": [
      { "fieldName": "vector", "indexName": "vector", "metricType": "COSINE", "params": { "index_type": "AUTOINDEX" } }
    ]
  }'

"code":0이 포함된 응답이 오면 컬렉션이 만들어진 것입니다.

연결 설정

AI DB 설정 화면의 로컬 AI DB 구성에서 아래와 같이 입력하고 저장합니다.

Milvus는 서비스형 저장소라 데이터 경로 입력란이 표시되지 않습니다. 저장하면 인덱싱 스케줄러가 새 설정을 확인하고, 필요한 경우 원본 전체 재인덱싱을 자동으로 시작합니다.

연결 확인

로컬 AI DB 운영 현황에서 상태를 확인합니다.

정상이 아닐 때는 아래를 확인하세요.

관련 문서

• AI DB 설정
• 벡터 DB 운영 가이드
• Qdrant 연결
• 지식 인덱싱