milvus-collection-builder

name

milvus-collection-builder

description

Create Milvus collections with natural language. Use when user wants to create Milvus collection, 向量数据库, vector database, RAG system, 知识库, knowledge base, text search, 文档搜索, document retrieval, semantic search, 语义搜索, 向量检索, or FAQ system. Supports preset scenes (text_search, rag) with optimized configurations. 适用于 "我要做RAG", "建个向量库", "文档搜索系统", "搞个知识库", "创建collection". Requires: OpenAI API key and local Milvus server running on localhost:19530.

Milvus Collection Builder

用一句话创建 Milvus Collection，无需关心 Milvus 概念。

前置条件

1. 安装依赖

pip install -U pymilvus openai langchain-openai langchain-text-splitters langchain-community python-dotenv

2. 启动 Milvus 服务器

# 使用 Docker
docker run -d -p 19530:19530 milvusdb/milvus:latest

# 或使用 Docker Compose
# https://milvus.io/docs/install_standalone-docker.md

3. 设置 OpenAI API Key（可选，用于 Embedding 功能）

export OPENAI_API_KEY="your-api-key-here"
# 或设置兼容的 API 地址
export OPENAI_BASE_URL="https://your-endpoint/v1"

4. 环境检测

运行环境检测脚本，确认当前环境满足要求：

cd ~/.claude/skills/milvus-skills && python3 scripts/check_env.py

检测脚本会检查：

• Python 版本 (需要 3.9+)
• pymilvus 包是否安装
• openai 包是否安装
• Milvus 服务器是否运行
• 技能文件是否完整

目录结构

~/.claude/skills/milvus-skills/
├── SKILL.md              # 技能说明文档（本文件）
├── README.md             # 项目说明
├── requirements.txt      # 依赖列表
├── scripts/              # 核心脚本目录
│   ├── __init__.py
│   ├── milvus_builder.py    # 核心构建器
│   ├── intent_parser.py     # 自然语言意图解析器
│   ├── check_env.py         # 环境检测脚本
│   └── insert_milvus_data.py # 数据插入脚本
└── examples/             # 示例代码目录
    ├── __init__.py
    ├── basic_text_search.py      # 文本搜索示例
    └── rag_knowledge_base.py     # RAG 知识库示例

执行方式

重要: 所有 Python 命令必须先切换到技能目录执行，以确保使用技能目录下的代码：

cd ~/.claude/skills/milvus-skills && python3 -c "你的代码"

示例：

cd ~/.claude/skills/milvus-skills && python3 -c "
from scripts.milvus_builder import MilvusCollectionBuilder
builder = MilvusCollectionBuilder()
result = builder.create_from_preset('my_kb', scene='rag')
print(result['code'])
"

核心文件

scripts/milvus_builder.py

核心构建器，提供 MilvusCollectionBuilder 类。

scripts/intent_parser.py

自然语言意图解析器，将用户输入转换为配置参数。

scripts/check_env.py

环境检测脚本，检查 Python 环境和依赖是否满足要求。

scripts/insert_milvus_data.py

数据插入脚本，将 Markdown 文档加载、切块、生成向量并插入到 Milvus Collection。

使用方法

基本用法

from scripts.milvus_builder import MilvusCollectionBuilder

# 创建构建器（连接到 localhost:19530）
builder = MilvusCollectionBuilder()

# 从预设场景创建 Collection
result = builder.create_from_preset(
    collection_name="my_docs",
    scene="text_search"  # 或 "rag"
)

# 检查结果
if result["status"] == "success":
    print(result["code"])  # 查看生成的代码
else:
    print(f"Error: {result['error']}")

使用意图解析

from scripts.intent_parser import IntentParser
from scripts.milvus_builder import MilvusCollectionBuilder

# 解析用户意图
parser = IntentParser()
intent = parser.parse("我要建一个RAG知识库")

# 使用解析结果创建
builder = MilvusCollectionBuilder()
result = builder.create_from_intent(
    collection_name="my_kb",
    **intent
)

插入数据

cd ~/.claude/skills/milvus-skills && python3 scripts/insert_milvus_data.py

该脚本会：

1. 读取 milvus_concepts.md 文件
2. 将文档切块（500字符，50重叠）
3. 使用 OpenAI Embedding 生成向量
4. 插入到 rag_kb collection
5. 创建 HNSW 索引

自定义连接地址

# 连接到远程 Milvus
builder = MilvusCollectionBuilder(
    uri="https://your-milvus.endpoint",
    token="your_api_key"
)

支持的场景

1. text_search (文本语义搜索)

• 关键词: 文本、文档、语义、搜索、检索、text、document、semantic、search、faq
• 适用: 文档检索、语义搜索、FAQ 问答
• 默认字段: id, content, vector
• 配置: COSINE 相似度, AUTOINDEX, 动态字段

2. rag (RAG 知识库)

• 关键词: rag、RAG、知识库、knowledge、kb
• 适用: RAG 应用、知识库问答、企业文档库
• 默认字段: id, text, metadata, vector
• 配置: COSINE 相似度, AUTOINDEX, 动态字段

支持的 Embedding 模型

模型	维度	关键词
OpenAI text-embedding-3-large	3072	3-large, 3072
OpenAI text-embedding-3-small	1536	3-small, 1536, openai (默认)
OpenAI text-embedding-ada-002	1536	ada, ada-002
BGE-M3	1024	bge-m3
BGE-Large	1024	bge-large
E5-Large	1024	e5

Embedding 功能

初始化

# 使用环境变量 OPENAI_API_KEY
builder.init_embedding()

# 或直接传入 API Key
builder.init_embedding(api_key="your-api-key")

# 使用兼容 OpenAI API 的服务
builder.init_embedding(api_key="key", base_url="https://your-endpoint")

生成向量

# 单个文本
vector = builder.embed_text("测试文本")

# 批量
vectors = builder.embed_text(["文本1", "文本2"])

# 生成并插入
result = builder.embed_and_insert(
    collection_name="my_docs",
    texts=["Milvus 是向量数据库", "向量搜索很重要"]
)

用户触发词

当用户提到以下内容时使用此技能：

• "创建 Milvus collection"
• "建一个向量数据库"
• "我要做文档搜索"
• "建一个 RAG 知识库"
• "create text search collection"
• "build RAG knowledge base"
• "语义搜索"、"向量检索"

工作流程

1. 解析用户意图: 使用 IntentParser 解析场景、模型、配置
2. 创建构建器: 初始化 MilvusCollectionBuilder
3. 创建 Collection: 调用 create_from_preset() 或 create_from_intent()
4. 返回结果: 显示生成的代码或错误信息

新对话触发

技能会在新对话中自动触发，当用户提到以下关键词时：

• "milvus"
• "向量数据库"
• "vector database"
• "collection"
• "rag"
• "知识库"

触发后，技能会重新运行完整流程，引导用户完成：

1. 环境检测
2. 意图解析
3. Collection 创建
4. 数据插入（可选）

限制

• 不支持多向量字段
• 不支持嵌套字段、数组类型
• 不支持分区键配置
• 不支持高级索引参数调优
• 本地 Embedding 模型 (BGE, E5) 仅用于配置维度，实际生成需用对应库

示例代码位置

• examples/basic_text_search.py: 文本搜索示例
• examples/rag_knowledge_base.py: RAG 知识库示例