Разбор навыков 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) или взвешенное ранжирование объединяет два списка.

Три строительных блока:

1. AnnSearchRequest — по одному на каждую ветку поиска
2. RRFRanker / WeightedRanker — стратегия слияния
3. 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:

1. Деструктивные операции требуют явного подтверждения пользователя. В руководстве модуля cluster сказано: "Перед удалением кластера всегда подтверждайте действие с пользователем — это необратимо." Каждая деструктивная операция (коллекции, резервные копии, базы данных, пользователи) содержит ту же инструкцию.
2. Чувствительные команды выполняются в собственном терминале пользователя. Модуль setup говорит прямо: "Команды входа (zilliz login, zilliz configure) требуют интерактивного терминала и НЕ МОГУТ выполняться внутри Claude Code. Всегда инструктируйте пользователя запускать их в собственном терминале." Учетные данные не проходят через агента.
3. Учетные данные никогда не выводятся. Аутентификация проходит через браузерный поток OAuth, API-ключ из консоли или переменную окружения ZILLIZ_API_KEY. Skill никогда не печатает секреты.

Это звучит базово, но агент с учетными данными Cloud и без слоя подтверждения мог бы воспринять "очисти тестовые кластеры" и снести production. Skill закрывает этот пробел на уровне инструкций, до того как любая деструктивная команда попадет в API.

Шлюз предварительных условий: три проверки перед запуском любой команды

Каждый sub-skill выполняет трехэтапную проверку, определенную в skills/setup/SKILL.md:

1. zilliz-cli установлен? Если нет, установить.
2. Пользователь вошел в систему? Если нет, направить на аутентификацию.
3. Контекст кластера установлен? Если нет, предложить выбор.

Шлюз гарантирует, что среда готова до выполнения любой команды, что надежнее, чем запускать вслепую и отлаживать ошибки после.

Почему это 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 опираются на четыре общих проектных решения:

1. У этих двух Skill четкие, не пересекающиеся роли. Milvus Skill отвечает за слой написания кода с SDK; Zilliz Cloud Skill отвечает за слой CLI-операций. Вместе они покрывают полный жизненный цикл векторной базы данных, не мешая друг другу.
2. Модульная загрузка знаний сохраняет контекст компактным. Разделение знаний на 7 и 14 справочных файлов позволяет агенту загружать только тот файл, который соответствует текущей задаче, вместо того чтобы переполнять окно контекста всей документацией.
3. Zilliz Cloud Skill закладывает безопасность на уровне инструкций. Подтверждение разрушительных операций, защита учетных данных и проверки предварительных условий показывают, что команда тщательно продумала, что агент с Cloud-ключами может сделать с работающей базой данных.
4. 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 для полного охвата продукта.