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 模型

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 知识库示例