Разбор навыков Zilliz: как ИИ-агенты осваивают векторные базы данных
Автор оригинала — ShugeX, независимый практик AI-ops и активный участник сообщества Milvus. Переведено и переопубликовано с разрешения.
Представьте, что вы используете Claude Code для создания RAG-приложения с Milvus. Каждый шаг — создание коллекции, определение схемы, вставка векторов, выполнение гибридного поиска — заставляет вас переключаться к документации pymilvus, чтобы найти нужный API, а затем возвращаться в редактор, чтобы встроить его в код. А если вы работаете в Zilliz Cloud, вы также переключаетесь в браузер, чтобы войти в консоль для управления кластерами, мониторинга и настройки резервного копирования. Среда разработки и среда эксплуатации — это два разных мира.
Два недавних Claude Code Skills от Zilliz нацелены именно на эту точку разрыва. Milvus Skill учит агента работать с векторной базой данных через Python SDK. Zilliz Cloud Skill учит агента управлять всем на стороне облака через zilliz-cli. Каждый Skill отвечает за одну область; вместе они превращают разработку и эксплуатацию в один непрерывный сеанс Claude Code.
После того как я полностью изучил исходный код обоих Skills, я нашел много того, что стоит разобрать, — модульный дизайн, паттерны безопасности и то, где Skill сочетается с MCP. В этой статье мы пройдемся по каждому из них.
Что делают Milvus Skill и Zilliz Cloud Skill по отдельности
Эти два Skills — не две версии одной и той же вещи. Они нацелены на две разные ошибки корректности.
Milvus Skill (zilliztech/milvus-skill) учит агента pymilvus, Python SDK для подключения, создания коллекций, вставки векторов и выполнения поиска. Это ассистент для написания кода, и он работает с любым развертыванием Milvus: Milvus Lite, self-hosted Standalone/Cluster или Zilliz Cloud. Ошибка, которую он исправляет: код pymilvus, который компилируется, но делает не то, что вы просили, потому что агент использовал устаревшую форму API.
Zilliz Cloud Skill (zilliztech/zilliz-skill) учит агента zilliz-cli, инструменту командной строки, который охватывает кластеры, резервные копии, мониторинг и биллинг. Это DBA-ассистент, и он работает только с Zilliz Cloud (у self-hosted Milvus нет control plane). Ошибка, которую он исправляет: галлюцинированные команды для живой production-системы, где неудачный zilliz cluster delete стоит дороже, чем ошибка компиляции.
В одну строку:
- Milvus Skill → агент пишет код, который работает с данными
- Zilliz Cloud Skill → агент выполняет команды, которые управляют сервисами
| Измерение | Milvus Skill | Zilliz Cloud Skill |
|---|---|---|
| Интерфейс | Python (pymilvus) | CLI (zilliz-cli) |
| Роль | Ассистент для написания кода | DBA-ассистент |
| Работает с | Все развертывания Milvus + Zilliz Cloud | Только Zilliz Cloud |
| Файлы | 7 справочных модулей | 14 sub-skills |
| Цель корректности | Устаревшие SDK API | Недостаточно документированные ops-команды |
| Типичная задача | Создать коллекцию, вставить, найти | Развернуть кластер, настроить резервное копирование, проверить биллинг |
Milvus Skill: обучение агента писать надежный pymilvus
Папка references/ в Milvus Skill содержит семь файлов, каждый из которых соответствует отдельной области возможностей pymilvus. Когда агент выполняет конкретную задачу, он загружает только соответствующий файл, а не сбрасывает всю документацию в контекст:
| Файл | Охватывает |
|---|---|
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-битное число с плавающей точкой, используется по умолчаниюFLOAT16_VECTOR— половинная точность, экономит памятьBFLOAT16_VECTOR— BF16, распространён в пайплайнах глубокого обученияBINARY_VECTOR— бинарныйSPARSE_FLOAT_VECTOR— разреженный, для полнотекстового поискаINT8_VECTOR— квантованный, дополнительное сжатие
Гибридный поиск: самая примечательная функция, которую охватывают эти Skills
patterns.md документирует четыре распространённых шаблона. У гибридного поиска больше всего составляющих. Поиск по плотным векторам (семантический) и поиск по разреженным векторам (ключевые слова) выполняются параллельно, затем RRF (Reciprocal Rank Fusion) или взвешенное ранжирование объединяет два списка.
Три строительных блока:
AnnSearchRequest— по одному на каждую ветку поискаRRFRanker/WeightedRanker— стратегия слиянияSPARSE_FLOAT_VECTOR— поле разреженного вектора
RRF прост: для каждого результата score = 1/rank, суммируется по веткам. Элементы с более высоким рангом побеждают. WeightedRanker — это взвешенная сумма по каждой ветке. Skill подробно это объясняет, поэтому агент генерирует пригодный к использованию код гибридного поиска без необходимости для разработчика читать статью про RRF.
Встроенный полнотекстовый поиск BM25 в Milvus
Milvus Skill также кодирует: встроенный полнотекстовый поиск Sparse-BM25 в Milvus 2.5. В сочетании с 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-вызовы к действующей control plane — и поскольку плохая команда может стереть production, 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 Sub-Skills, охватывающих полный облачный жизненный цикл
Репозиторий zilliz-plugin поставляется с 14 sub-skills, каждый в 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:
- Деструктивные операции требуют явного подтверждения пользователя. В руководстве модуля cluster сказано: "Перед удалением кластера всегда подтверждайте действие с пользователем — это необратимо." Каждая деструктивная операция (коллекции, резервные копии, базы данных, пользователи) содержит ту же инструкцию.
- Чувствительные команды выполняются в собственном терминале пользователя. Модуль
setupговорит прямо: "Команды входа (zilliz login, zilliz configure) требуют интерактивного терминала и НЕ МОГУТ выполняться внутри Claude Code. Всегда инструктируйте пользователя запускать их в собственном терминале." Учетные данные не проходят через агента. - Учетные данные никогда не выводятся. Аутентификация проходит через браузерный поток OAuth, API-ключ из консоли или переменную окружения
ZILLIZ_API_KEY. Skill никогда не печатает секреты.
Это звучит базово, но агент с учетными данными Cloud и без слоя подтверждения мог бы воспринять "очисти тестовые кластеры" и снести production. Skill закрывает этот пробел на уровне инструкций, до того как любая деструктивная команда попадет в API.
Шлюз предварительных условий: три проверки перед запуском любой команды
Каждый sub-skill выполняет трехэтапную проверку, определенную в skills/setup/SKILL.md:
zilliz-cliустановлен? Если нет, установить.- Пользователь вошел в систему? Если нет, направить на аутентификацию.
- Контекст кластера установлен? Если нет, предложить выбор.
Шлюз гарантирует, что среда готова до выполнения любой команды, что надежнее, чем запускать вслепую и отлаживать ошибки после.
Почему это Zilliz Skills, а не просто MCP?
Zilliz поставляет оба варианта, потому что они решают разные задачи. Skill внедряет знания, к которым агент обращается при написании кода. MCP-сервер предоставляет вызываемые конечные точки, которые агент может вызывать. mcp-server-milvus — это MCP-направление; Milvus Skill — направление знаний. Они дополняют друг друга, а не конкурируют.
Skill — это загрузчик промптов
Минимальный Skill — это папка и SKILL.md:
my-skill/
├── SKILL.md # instructions + metadata
├── references/ # reference docs (optional)
├── scripts/ # executable scripts (optional)
└── assets/ # templates, resources (optional)
SKILL.md — это инструкция. Она сообщает агенту, как обрабатывать конкретную задачу. Никакого исполняемого кода, никакого серверного процесса. Только структурированные знания, внедряемые в контекст модели по требованию.
Skill — это загрузчик промптов. Предметные знания, упакованные как структурированный промпт и загружаемые динамически.
MCP — это протокол инструментов
MCP (Model Context Protocol) принимает другую форму. Это стандартизированный протокол, который позволяет агенту вызывать внешние инструменты через единый интерфейс. mcp-server-milvus — это MCP-сервер, который предоставляет конечные точки инструментов, такие как milvus_text_search, milvus_create_collection и так далее.
MCP описывали как «порт USB-C для AI-агентов». Он решает проблему стандартизации интерфейса инструментов.
Zilliz Skill vs zilliz MCP
| Измерение | Skill | MCP |
|---|---|---|
| Суть | Внедрение знаний (prompt) | Вызов инструментов (protocol) |
| Что делает | Изменяет то, как ведет себя агент | Дает агенту новую возможность |
| Стоимость развертывания | Поместить файлы — готово | Требуется серверный процесс |
| Подходит для | Обучения агента использовать инструменты, которые у него уже есть | Предоставления агенту инструментов, которых у него нет |
| Зависимость | Агент поддерживает загрузку 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. Один проект skill-пакетов на GitHub набрал 6 600 звезд за пять дней в апреле 2026 года.
Реальные сценарии: как разработчики на самом деле их используют
Сценарий 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, комбинация AUTOINDEX с метрикой BM25: все это не те вещи, которые вы хотите, чтобы агент угадывал. Skill их кодирует.
Сценарий 2: Управление кластером Zilliz Cloud
"Создай Serverless-кластер в us-east-1, затем создай коллекцию с 768-мерными векторами."
Агент выполняет проверку предварительных условий, затем по порядку выдает CLI-команды. Или:
"Покажи мне статус и использование ресурсов всех моих кластеров."
Агент выполняет zilliz cluster list и соответствующие команды zilliz monitoring, затем делает сводку. Учетные данные никогда не покидают ваш терминал.
Сценарий 3: Резервные копии и миграция данных
"Настрой ежедневную политику резервного копирования для production, хранить 7 дней."
backup.md документирует полный синтаксис политики. Агент настраивает политику напрямую.
"Экспортируй коллекцию orders из тестового кластера в S3."
import.md охватывает массовый импорт и экспорт из облачного хранилища, включая поддерживаемые форматы (Parquet, JSON, CSV).
Сценарий 4: Переход на гибридный поиск
"Обнови мой поиск до гибридного dense + sparse с RRF."
Агент берет заметки из vector.md об AnnSearchRequest и RRFRanker и пишет код гибридного поиска. Вам не нужно изучать параметры RRF.
Стек агентов Zilliz: где применяются эти два навыка
Эти два Skill являются частью более широкой инициативы Zilliz по всем паттернам интеграции агентов:
| Проект | Тип | Охватывает |
|---|---|---|
| mcp-server-milvus | MCP Server | Операции с базой данных Milvus |
| claude-context | MCP Server | Семантический поиск по коду |
| milvus-skill | Skill | pymilvus SDK |
| zilliz-skill | Skill | Управление Zilliz Cloud |
| DeepSearcher | Agent framework | Многошаговый агентный RAG |
claude-context выделяется особенно. Он индексирует кодовую базу в векторной БД, извлекает релевантный код по запросу с помощью гибридного поиска (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 получает покрытие независимо от того, в каком направлении будет развиваться экосистема интеграции агентов.
Если вы создаете агентов для работы с векторной БД, установите оба Skill в следующий раз, когда будете запускать RAG-приложение или управлять кластером.
Начало работы
Установите два Skill в следующей сессии Claude Code:
- Milvus Skill — корректность pymilvus. Работает с Milvus Lite, самостоятельно развернутыми Standalone/Cluster и Zilliz Cloud.
- Zilliz Cloud Skill — управление работающим кластером через
zilliz-cli. Установите CLI вместе с ним.
Если у вас еще нет кластера, зарегистрируйтесь в Zilliz Cloud (новые аккаунты с рабочей почтой получают бесплатные кредиты) или войдите, затем вставьте Skill в Claude Code, и агент сделает все остальное.
Дополнительные материалы
- "MCP мёртв?" — взгляд Zilliz на то, где CLI и Skills находятся рядом с MCP.
- Milvus SDK Code Helper — аналог MCP для Milvus Skill, та же проблема с устаревшим pymilvus с другой стороны.
claude-context— семантический поиск по кодовой базе, сообщающий о сокращении токенов примерно на 40%.- документация Milvus и Zilliz Cloud для полного охвата продукта.
Читать далее
What Is a Vector Lakebase?
A Vector Lakebase is a unified, lake-native data architecture for AI that combines vector-database-grade serving with open lake storage, reusable lake-level indexes, and a shared semantic layer.
8 Latest RAG Advancements Every Developer Should Know
Explore eight advanced RAG variants that can solve real problems you might be facing: slow retrieval, poor context understanding, multimodal data handling, and resource optimization.
OpenAI o1: What Developers Need to Know
In this article, we will talk about the o1 series from a developer's perspective, exploring how these models can be implemented for sophisticated use cases.