Zilliz 기술 분석: AI 에이전트가 벡터 데이터베이스를 마스터하는 방법
원문 작성자: 독립 AI-ops 실무자이자 활발한 Milvus 커뮤니티 기여자인 ShugeX. 허가를 받아 번역 및 재게시되었습니다.
Milvus로 RAG 앱을 구축하기 위해 Claude Code를 사용한다고 상상해 보세요. 모든 단계 — 컬렉션 생성, 스키마 정의, 벡터 삽입, 하이브리드 검색 실행 — 마다 올바른 API를 찾기 위해 pymilvus 문서를 뒤적이고, 다시 에디터로 돌아와 연결해야 합니다. 그리고 Zilliz Cloud를 사용 중이라면 클러스터 관리, 모니터링, 백업 설정을 위해 브라우저로 이동해 콘솔에 로그인해야 합니다. 개발 환경과 운영 환경은 완전히 다른 두 세계입니다.
Zilliz의 최근 두 가지 Claude Code Skills는 바로 그 단절 지점을 겨냥합니다. Milvus Skill은 에이전트에게 Python SDK를 통해 벡터 데이터베이스를 운영하는 방법을 가르칩니다. Zilliz Cloud Skill은 에이전트에게 zilliz-cli를 통해 클라우드 측의 모든 것을 관리하는 방법을 가르칩니다. 각 Skill은 하나의 도메인을 담당하며, 함께 사용하면 개발과 운영을 하나의 연속적인 Claude Code 세션으로 바꿔 줍니다.
두 Skill의 소스 코드를 처음부터 끝까지 읽어 본 뒤, 모듈식 설계, 안전 패턴, 그리고 Skill이 MCP와 나란히 어디에 적합한지 등 살펴볼 만한 점이 많다는 것을 발견했습니다. 이 글에서는 각각을 살펴봅니다.
Milvus Skill과 Zilliz Cloud Skill이 각각 하는 일
두 Skill은 하나의 기능에 대한 두 가지 버전이 아닙니다. 서로 다른 두 가지 정확성 실패를 겨냥합니다.
Milvus Skill(zilliztech/milvus-skill)은 에이전트에게 연결, 컬렉션 생성, 벡터 삽입, 검색 실행을 위한 Python SDK인 pymilvus를 가르칩니다. 이는 코딩 어시스턴트이며, Milvus Lite, self-hosted Standalone/Cluster, 또는 Zilliz Cloud 등 모든 Milvus 배포 환경에서 작동합니다. 이것이 해결하는 실패는 에이전트가 오래된 API 형태를 사용했기 때문에 컴파일은 되지만 요청한 대로 동작하지 않는 pymilvus 코드입니다.
Zilliz Cloud Skill(zilliztech/zilliz-skill)은 에이전트에게 클러스터, 백업, 모니터링, 결제를 다루는 명령줄 도구인 zilliz-cli를 가르칩니다. 이는 DBA 어시스턴트이며, Zilliz Cloud에서만 작동합니다(self-hosted Milvus에는 컨트롤 플레인이 없습니다). 이것이 해결하는 실패는 실제 프로덕션 시스템을 대상으로 한 환각 명령이며, 잘못된 zilliz cluster delete는 컴파일 오류보다 훨씬 더 큰 비용을 초래합니다.
한 줄 요약:
- Milvus Skill → 에이전트가 데이터를 다루는 코드를 작성함
- Zilliz Cloud Skill → 에이전트가 서비스를 관리하는 명령을 실행함
| Dimension | Milvus Skill | Zilliz Cloud Skill |
|---|---|---|
| 인터페이스 | Python (pymilvus) | CLI (zilliz-cli) |
| 역할 | 코딩 어시스턴트 | DBA 어시스턴트 |
| 작동 대상 | 모든 Milvus 배포 + Zilliz Cloud | Zilliz Cloud 전용 |
| 파일 | 7개 참조 모듈 | 14개 하위 Skill |
| 정확성 목표 | 오래된 SDK API | 문서화가 부족한 운영 명령 |
| 일반적인 작업 | 컬렉션 구축, 삽입, 검색 | 클러스터 프로비저닝, 백업 설정, 결제 확인 |
Milvus Skill: 에이전트에게 신뢰할 수 있는 pymilvus 작성을 가르치기
Milvus Skill의 references/ 폴더에는 7개의 파일이 있으며, 각각은 독립적인 pymilvus 기능 영역에 매핑됩니다. 에이전트가 특정 작업을 처리할 때 모든 문서를 컨텍스트에 쏟아붓는 대신 관련 파일만 로드합니다:
| File | Covers |
|---|---|
collection.md | 데이터 유형, 필드 정의, 컬렉션 작업 |
vector.md | 벡터 CRUD, 하이브리드 검색, 전문 검색, 이터레이터 |
index.md | 인덱스 유형, 메트릭 유형, 인덱스 관리 |
partition.md | 파티션 관리 |
database.md | 데이터베이스 관리 |
user-role.md | RBAC |
patterns.md | 일반 패턴(RAG, 하이브리드 검색 등) |
스키마를 구축하나요? 에이전트는 collection.md를 가져옵니다. 검색을 실행하나요? vector.md를 가져옵니다. 나머지는 제외됩니다. 컨텍스트 윈도우는 유한합니다. 모든 것을 쏟아붓는 것보다 온디맨드 로딩이 낫습니다.
지원되는 데이터 타입: 예상보다 더 풍부함
collection.md를 훑어보면, Milvus는 대부분의 개발자가 생각하는 것보다 더 많은 벡터 타입을 지원합니다:
- 스칼라:
BOOL,INT8/16/32/64,FLOAT,DOUBLE,VARCHAR,JSON,ARRAY - 벡터:
FLOAT_VECTOR— 32비트 float, 기본값FLOAT16_VECTOR— 반정밀도, 메모리 절약BFLOAT16_VECTOR— BF16, 딥러닝 파이프라인에서 일반적BINARY_VECTOR— 바이너리SPARSE_FLOAT_VECTOR— 희소, 전문 검색용INT8_VECTOR— 양자화, 추가 압축
하이브리드 검색: 이 Skill들이 다루는 가장 주목할 만한 기능
patterns.md는 네 가지 일반적인 패턴을 문서화합니다. 하이브리드 검색은 구성 요소가 가장 많습니다. 밀집 벡터 검색(의미 기반)과 희소 벡터 검색(키워드)이 병렬로 실행된 다음, RRF (Reciprocal Rank Fusion) 또는 가중 랭킹이 두 목록을 병합합니다.
세 가지 빌딩 블록:
AnnSearchRequest— 검색 브랜치당 하나RRFRanker/WeightedRanker— 융합 전략SPARSE_FLOAT_VECTOR— 희소 벡터 필드
RRF는 간단합니다. 각 결과에 대해 점수 = 1/rank이며, 브랜치 전체에서 합산됩니다. 더 높은 순위의 항목이 이깁니다. WeightedRanker는 브랜치별 가중 합입니다. Skill이 이를 명확히 설명하므로, 개발자가 RRF 논문을 읽지 않아도 에이전트가 사용 가능한 하이브리드 검색 코드를 생성합니다.
Milvus의 내장 BM25 전문 검색
Milvus Skill은 또한 다음을 인코딩합니다: Milvus 2.5의 내장 Sparse-BM25 전문 검색. Function 및 FunctionType.BM25와 결합하면, Milvus가 원시 텍스트를 내부적으로 희소 벡터로 변환하여 외부 임베딩 모델과 수동 TF-IDF 파이프라인을 건너뜁니다.
2.5 이전에는 전문 검색을 하려면 토크나이저를 다루고, TF-IDF를 직접 계산하고, 희소 벡터를 직접 생성해야 했습니다. 이제 원하는 것을 에이전트에게 말하면, Skill이 BM25 Function이 올바르게 연결된 컬렉션을 생성하도록 안내합니다.
검색 이터레이터: 백만 행 컬렉션을 위한 페이지네이션
vector.md는 또한 백만 또는 십억 행 컬렉션을 위한 커서 스타일 페이지네이션인 search_iterator와 query_iterator를 다룹니다. 일반 search는 고정 크기의 결과 집합을 반환합니다. 이터레이터는 누락이나 중복 없이 페이지를 넘기며, 이는 전체 열거에 필요한 방식입니다.
Zilliz Cloud Skill: 에이전트를 클라우드 DBA로 가르치기
Zilliz Cloud Skill의 역할은 Milvus Skill과 다릅니다. Python을 작성하는 대신, 에이전트는 라이브 컨트롤 플레인에 대해 CLI 호출을 구성합니다. 그리고 잘못된 명령 하나가 프로덕션을 지울 수 있기 때문에, Skill은 이러한 호출을 안전 규칙으로 감쌉니다.
명령 모드: 에이전트가 CLI 호출을 구성하는 방식
Skill은 일관된 명령 형태를 인코딩합니다:
zilliz <resource> <action> --flag <value>
예시:
zilliz cluster list— 모든 클러스터 나열zilliz collection create --name my_collection— 컬렉션 생성zilliz backup create --name daily-backup— 백업 생성
세 가지 출력 형식: json(기계가 읽을 수 있음), table(사람이 보기 좋음), text(일반 텍스트). 에이전트는 상황에 맞는 것을 선택합니다.
전체 클라우드 라이프사이클을 다루는 14개의 하위 Skill
zilliz-plugin 리포지토리는 14개의 하위 Skill을 제공하며, 각각 skills/<name>/SKILL.md 아래에 있습니다:
| 모듈 | 다루는 내용 |
|---|---|
setup | 설치, 인증(OAuth / API Key / env var), 컨텍스트 설정 |
cluster | 생성, 목록 조회, 수정, 일시 중지, 재개, 삭제 |
collection | 컬렉션 CRUD, 로드/릴리스, 별칭 |
vector | CLI를 통한 벡터 작업 |
index | 인덱스 관리 |
database | 데이터베이스 관리(Dedicated 전용) |
partition | 파티션 관리 |
user-role | RBAC(Dedicated 전용) |
backup | 생성, 복원, 내보내기, 백업 정책 |
import | 클라우드 스토리지에서 대량 가져오기(Parquet / JSON / CSV) |
billing | 사용량, 인보이스, 결제 수단 |
monitoring | 클러스터 상태, 통계, 로드 상태 |
project-region | 프로젝트 및 리전 관리 |
job | 비동기 작업 추적 |
클러스터를 띄우고, 백업 보존 기간을 구성하고, 인보이스를 확인하는 것까지: 14개 모듈이 모든 Zilliz Cloud 콘솔 작업을 다룹니다.
티어 인식이 내장되어 있습니다. database와 user-role은 Dedicated 전용으로 표시되어 있습니다. Skill은 Free, Serverless, Dedicated 티어가 서로 다른 기능을 가진다는 것을 알고 있으므로, 에이전트는 클러스터 티어가 지원할 수 없는 작업을 시도하지 않습니다.
모든 모듈에 적용되는 세 가지 안전 규칙
Zilliz Cloud Skill의 안전 설계는 Milvus Skill보다 여러 계층 더 깊습니다. 개별 SKILL.md 파일 전반에 세 가지 핵심 규칙이 나타납니다:
- 파괴적 작업에는 명시적인 사용자 확인이 필요합니다. 클러스터 모듈의 지침에는 다음과 같이 쓰여 있습니다: "클러스터를 삭제하기 전에 항상 사용자에게 확인하세요 — 이는 되돌릴 수 없습니다." 모든 파괴적 작업(컬렉션, 백업, 데이터베이스, 사용자)에도 동일한 지침이 적용됩니다.
- 민감한 명령은 사용자의 자체 터미널에서 실행됩니다.
setup모듈은 명확히 말합니다: "로그인 명령(zilliz login, zilliz configure)은 대화형 터미널이 필요하며 Claude Code 내부에서 실행할 수 없습니다. 항상 사용자에게 자신의 터미널에서 이를 실행하도록 안내하세요." 자격 증명은 에이전트를 통해 흐르지 않습니다. - 자격 증명은 절대 노출되지 않습니다. 인증은 OAuth 브라우저 플로우, 콘솔의 API 키, 또는
ZILLIZ_API_KEYenv var를 통해 이루어집니다. Skill은 비밀 정보를 절대 출력하지 않습니다.
이것들은 기본적으로 들리지만, Cloud 자격 증명을 가지고 확인 계층이 없는 에이전트라면 "테스트 클러스터 정리해 줘"라는 말만으로 프로덕션을 날려버릴 수 있습니다. Skill은 파괴적 명령이 API에 도달하기 전에, 지침 계층에서 그 간극을 메웁니다.
사전 조건 게이트: 명령 실행 전 세 가지 확인
모든 하위 Skill은 skills/setup/SKILL.md에 정의된 세 단계 확인을 실행합니다:
zilliz-cli가 설치되어 있나요? 그렇지 않다면 설치합니다.- 사용자가 로그인했나요? 그렇지 않다면 인증으로 안내합니다.
- 클러스터 컨텍스트가 설정되었나요? 그렇지 않다면 선택을 요청합니다.
이 게이트는 어떤 명령이 실행되기 전에 환경이 준비되었는지 보장하며, 이는 무작정 실행한 뒤 오류를 디버깅하는 것보다 더 안정적입니다.
왜 단순한 MCP가 아니라 Zilliz Skills인가요?
Zilliz는 두 가지가 서로 다른 문제를 해결하기 때문에 둘 다 제공합니다. Skill은 에이전트가 코드를 작성할 때 참조하는 지식을 주입합니다. MCP 서버는 에이전트가 호출할 수 있는 호출 가능한 엔드포인트를 노출합니다. mcp-server-milvus는 MCP 쪽이고, Milvus Skill은 지식 쪽입니다. 둘은 경쟁하기보다 계층을 이룹니다.
Skill은 프롬프트 로더입니다
최소 Skill은 폴더와 SKILL.md입니다:
my-skill/
├── SKILL.md # 지침 + 메타데이터
├── references/ # 참조 문서(선택 사항)
├── scripts/ # 실행 가능한 스크립트(선택 사항)
└── assets/ # 템플릿, 리소스(선택 사항)
SKILL.md는 지침서입니다. 주어진 작업을 어떻게 처리할지 에이전트에게 알려줍니다. 실행 코드도 없고, 서버 프로세스도 없습니다. 필요할 때 모델의 컨텍스트에 주입되는 구조화된 지식일 뿐입니다.
Skill은 프롬프트 로더입니다. 구조화된 프롬프트로 패키징되어 동적으로 로드되는 도메인 지식입니다.
MCP는 도구 프로토콜입니다
MCP(Model Context Protocol)는 다른 형태를 띱니다. 이는 에이전트가 통일된 인터페이스를 통해 외부 도구를 호출할 수 있게 해주는 표준화된 프로토콜입니다. mcp-server-milvus는 milvus_text_search, milvus_create_collection 등과 같은 도구 엔드포인트를 노출하는 MCP 서버입니다.
MCP는 "AI 에이전트를 위한 USB-C 포트"라고 설명되어 왔습니다. 이는 도구 인터페이스 표준화 문제를 해결합니다.
Zilliz Skill vs zilliz MCP
| 차원 | Skill | MCP |
|---|---|---|
| 본질 | 지식 주입(프롬프트) | 도구 호출(프로토콜) |
| 하는 일 | 에이전트의 동작 방식을 수정 | 에이전트에 새로운 기능을 부여 |
| 배포 비용 | 파일을 넣으면 끝 | 서버 프로세스 필요 |
| 적합한 경우 | 에이전트가 이미 가진 도구를 사용하도록 가르치기 | 에이전트가 갖고 있지 않은 도구를 제공하기 |
| 의존성 | 에이전트가 Skill 로딩을 지원 | 에이전트가 MCP를 지원 |
핵심적인 차이는 이것입니다. Milvus Skill은 에이전트에게 pymilvus 사용법을 가르칩니다. pymilvus는 이미 존재합니다. Skill은 기능을 추가하지 않습니다. 에이전트가 이미 가진 기능의 정확성을 바로잡습니다. 반대로 MCP는 에이전트가 다른 방식으로는 도달할 수 없는 호출 가능한 엔드포인트를 제공합니다.
Skill은 이미 소유한 기계를 위한 사용 설명서입니다. MCP는 새로운 기계를 움직이게 하는 리모컨입니다. Zilliz는 "Is MCP Dead? MCP vs CLI vs Agent Skills Compared"에서 이를 직접적으로 말했습니다. 두 패턴은 모두 지속됩니다.
그렇지만 Skills는 빠르게 확산되고 있습니다. 커뮤니티 트래커에 따르면 레지스트리 전반에 700,000개 이상의 패키지가 있으며, ClawHub만 해도 5,700개 이상의 skills를 등재하고 있습니다. GitHub의 한 skill-package 프로젝트는 2026년 4월 5일 만에 6,600개의 스타를 받았습니다.
실제 시나리오: 개발자들이 실제로 사용하는 방식
시나리오 1: RAG 애플리케이션 구축
RAG 앱을 만들고 있다고 해봅시다. Milvus Skill이 설치된 상태에서 이렇게 말합니다.
"문서 검색 컬렉션을 생성해줘: 768차원 벡터, BM25 전체 텍스트 검색, title, body, embedding 필드."
에이전트는 collection.md와 patterns.md를 가져와 다음을 작성합니다.
from pymilvus import MilvusClient, DataType, Function, FunctionType
client = MilvusClient(uri="<URI>", token="<TOKEN>")
schema = client.create_schema(auto_id=True)
schema.add_field("id", DataType.INT64, is_primary=True)
schema.add_field("title", DataType.VARCHAR, max_length=512)
schema.add_field("body", DataType.VARCHAR, max_length=4096, enable_analyzer=True)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=768)
schema.add_field("body_sparse", DataType.SPARSE_FLOAT_VECTOR)
# Wire BM25 full-text search
schema.add_function(Function(
name="body_bm25",
input_field_names=["body"],
output_field_names=["body_sparse"],
function_type=FunctionType.BM25,
))
index_params = client.prepare_index_params()
index_params.add_index(field_name="embedding", index_type="AUTOINDEX", metric_type="COSINE")
index_params.add_index(field_name="body_sparse", index_type="AUTOINDEX", metric_type="BM25")
client.create_collection("documents", schema=schema, index_params=index_params)
enable_analyzer=True, BM25 Function 연결, BM25 metric과 함께 쓰는 AUTOINDEX 조합: 이런 것들은 에이전트가 추측하게 두고 싶지 않은 요소입니다. Skill은 이를 인코딩합니다.
시나리오 2: Zilliz Cloud 클러스터 관리
"us-east-1에 Serverless 클러스터를 생성한 다음, 768차원 벡터 컬렉션을 만들어줘."
에이전트는 사전 요구 사항 확인을 실행한 뒤 CLI 명령을 순서대로 실행합니다. 또는:
"내 모든 클러스터의 상태와 리소스 사용량을 보여줘."
에이전트는 zilliz cluster list와 해당 zilliz monitoring 명령을 실행한 뒤 요약합니다. 자격 증명은 터미널 밖으로 나가지 않습니다.
시나리오 3: 백업과 데이터 마이그레이션
"프로덕션용 일일 백업 정책을 설정하고, 7일 동안 보관해줘."
backup.md는 전체 정책 구문을 문서화합니다. 에이전트가 정책을 직접 구성합니다.
"테스트 클러스터의 orders 컬렉션을 S3로 내보내줘."
import.md는 지원되는 형식(Parquet, JSON, CSV)을 포함하여 클라우드 스토리지에서의 대량 가져오기 및 내보내기를 다룹니다.
시나리오 4: 하이브리드 검색으로 업그레이드
"내 검색을 RRF를 사용하는 dense + sparse 하이브리드로 업그레이드해줘."
에이전트는 AnnSearchRequest 및 RRFRanker에 대한 vector.md의 메모를 가져와 하이브리드 검색 코드를 작성합니다. RRF 매개변수를 공부할 필요는 없습니다.
Zilliz의 에이전트 스택: 두 Skill이 들어맞는 위치
이 두 Skill은 모든 에이전트 통합 패턴 전반에 걸친 더 광범위한 Zilliz 노력 안에 자리합니다:
| 프로젝트 | 유형 | 다루는 내용 |
|---|---|---|
| mcp-server-milvus | MCP Server | Milvus 데이터베이스 작업 |
| claude-context | MCP Server | 시맨틱 코드 검색 |
| milvus-skill | Skill | pymilvus SDK |
| zilliz-skill | Skill | Zilliz Cloud 관리 |
| DeepSearcher | 에이전트 프레임워크 | 다단계 에이전트형 RAG |
claude-context가 단연 돋보입니다. 코드베이스를 벡터 DB에 인덱싱하고, 하이브리드(BM25 + dense) 검색으로 필요할 때 관련 코드를 검색하며, 동등한 검색 품질에서 약 40%의 토큰 감소를 보고합니다.
MCP에서 Skill, 코드 검색, 에이전트 프레임워크에 이르기까지 Zilliz의 전략은 일관됩니다: 어떤 에이전트 통합 패턴이 승리하든, 벡터 데이터베이스는 일급 진입점을 가져야 한다는 것입니다. 두 Skill은 그 경로에 대한 Zilliz의 진입입니다.
결론
Milvus Skill과 Zilliz Cloud Skill은 공통적으로 네 가지 설계 선택에 의존합니다:
- 두 Skill은 명확하고 겹치지 않는 역할을 가집니다. Milvus Skill은 SDK 코딩 계층을 처리하고, Zilliz Cloud Skill은 CLI 운영 계층을 처리합니다. 함께 이들은 서로의 영역을 침범하지 않으면서 전체 벡터 데이터베이스 수명 주기를 포괄합니다.
- 모듈식 지식 로딩은 컨텍스트를 간결하게 유지합니다. 지식을 7개 및 14개의 참조 파일로 나누면, 에이전트가 모든 문서로 컨텍스트 창을 넘치게 하는 대신 현재 작업과 일치하는 파일만 가져올 수 있습니다.
- Zilliz Cloud Skill은 안전성을 지침 계층에 내장합니다. 파괴적 작업 확인, 자격 증명 보호, 사전 요구 사항 검사는 팀이 Cloud 키를 가진 에이전트가 라이브 데이터베이스에 대해 무엇을 할 수 있는지 신중하게 생각했음을 보여줍니다.
- Zilliz는 승자를 고르는 것이 아니라 패러다임 전반에 걸쳐 헤지하고 있습니다. MCP와 Skill 구현을 모두 제공함으로써, Zilliz는 에이전트 통합 생태계가 어느 방향으로 움직이든 대비할 수 있습니다.
벡터 DB를 대상으로 에이전트를 구축하고 있다면, 다음에 RAG 앱을 시작하거나 클러스터를 관리할 때 두 Skill을 모두 설치하세요.
시작하기
다음 Claude Code 세션에서 두 Skill을 설치하세요:
- Milvus Skill — pymilvus 정확성. Milvus Lite, 자체 호스팅 Standalone/Cluster, Zilliz Cloud에서 작동합니다.
- Zilliz Cloud Skill —
zilliz-cli를 통한 라이브 클러스터 관리. CLI도 함께 설치하세요.
아직 클러스터가 없다면, Zilliz Cloud에 가입하거나(새 회사 이메일 계정은 무료 크레딧을 받습니다) 로그인한 다음, Skill을 Claude Code에 붙여넣으면 에이전트가 그다음부터 처리합니다.
추가 자료
- "MCP는 죽었는가?" — MCP와 함께 CLI 및 Skills가 어디에 위치하는지에 대한 Zilliz의 프레이밍.
- Milvus SDK Code Helper — Milvus Skill에 대응하는 MCP로, 동일한 outdated-pymilvus 문제를 다른 각도에서 다룹니다.
claude-context— 약 40%의 토큰 감소를 보고하는 시맨틱 코드베이스 검색.- 전체 제품 범위는 Milvus docs 및 Zilliz Cloud를 참조하세요.
계속 읽기
How Zilliz Saw the Future of Vector Databases—and Built for Production
An inside look at how Zilliz built vector databases for real-world use, focusing on scalability, stability, and running them reliably at scale.
The Real Bottlenecks in Autonomous Driving — And How AI Infrastructure Can Solve Them
Autonomous driving faces a data bottleneck. Learn how AI-native vector databases like Zilliz solve scale, cost, and insight challenges across AV pipelines.
The Great AI Agent Protocol Race: Function Calling vs. MCP vs. A2A
Compare Function Calling, MCP, and A2A protocols for AI agents. Learn which standard best fits your development needs and future-proof your applications.