VuePress 站点

🎯 课程主题

通过 pymilvus SDK 连接本地 Milvus 服务，学习 DDL 操作：数据库的增删查、Collection 的创建与删除，建立 Python 操作 Milvus 的基本能力。

📝 核心知识点

1. MilvusClient 客户端连接

连接方式：HTTP 方式连接本地 Milvus 实例，默认端口 19530。
类比：类似 MySQL 的 pymysql.connect(host, port)。
连接地址：http://localhost:19530（本地单机版）。

2. Database（数据库）操作

操作	方法	说明
列出所有数据库	`client.list_databases()`	默认有一个 `default` 数据库
创建数据库	`client.create_database(db_name)`	可先判断是否存在：`if db_name not in existing_dbs`
切换/使用数据库	`client.use_database(db_name)`	类似 MySQL 的 `USE database`
删除数据库	`client.drop_database(db_name)`	⚠️ 必须先清空该库下所有 Collection

3. Collection（集合）操作

操作	方法	说明
列出所有集合	`client.list_collections()`	调用前需先 `use_database`
创建集合	`client.create_collection(...)`	核心参数见下方
删除集合	`client.drop_collection(name)`	不存在时也不会报错

4. 创建 Collection 的核心参数

参数	说明	示例
`collection_name`	集合名称（类似表名）	`"docs"`
`dimension`	向量维度，必须与 Embedding 模型输出一致	`1024`（BGE 模型）或 `3072`（text-embedding-3-large）
`metric_type`	向量相似度度量方式	`"COSINE"`（余弦相似度，默认推荐）

5. 余弦相似度 (Cosine Similarity) 详解

原理：计算两个向量在高维空间中的夹角余弦值。
取值范围：[0, 1]（因为 Embedding 向量的标量均为正数，所有向量都在第一象限，夹角不超过 90°）。
解读：
- 越接近 1 → 夹角越小 → 两个向量越相似
- 越接近 0 → 夹角接近 90° → 完全不相似
其他可选的 metric_type："L2"（欧氏距离）、"IP"（内积）。

🏗️ 架构与工作流

DDL 操作流程：

1. 创建客户端连接
   │
   ├── 2. 查看所有数据库 ──▶ list_databases()
   │
   ├── 3. 创建新数据库 ──▶ create_database("rag_demo")
   │       │
   │       ├── 4. 切换到该数据库 ──▶ use_database("rag_demo")
   │       │
   │       ├── 5. 查看所有 Collection ──▶ list_collections()
   │       │
   │       ├── 6. 创建 Collection ──▶ create_collection(
   │       │       collection_name="docs",
   │       │       dimension=1024,
   │       │       metric_type="COSINE"
   │       │   )
   │       │
   │       └── 7. 删除 Collection ──▶ drop_collection("docs")
   │
   └── 8. 删除数据库 ──▶ drop_database("rag_demo")

💻 代码实战

完整 DDL 操作示例

from pymilvus import MilvusClient

# =============================================
# 1. 创建客户端连接
# =============================================
client = MilvusClient(uri="http://localhost:19530")

# =============================================
# 2. 列出所有数据库
# =============================================
existing_databases = client.list_databases()
print("现有数据库：")
for db in existing_databases:
    print(f"  - {db}")
# 默认输出: default

# =============================================
# 3. 创建数据库
# =============================================
db_name = "rag_demo"

if db_name not in existing_databases:
    client.create_database(db_name)
    print(f"数据库 '{db_name}' 创建成功")

# 验证
existing_databases = client.list_databases()
print(f"创建后: {existing_databases}")
# 输出: ['default', 'rag_demo']

# =============================================
# 4. 切换/使用数据库
# =============================================
client.use_database(db_name)

# =============================================
# 5. 列出当前数据库下的所有 Collection
# =============================================
collections = client.list_collections()
print(f"当前数据库下的 Collection: {collections}")
# 初始为空: []

# =============================================
# 6. 创建 Collection
# =============================================
collection_name = "docs"

client.create_collection(
    collection_name=collection_name,
    dimension=1024,                # 必须与 Embedding 模型维度一致
    metric_type="COSINE"           # 余弦相似度
)
print(f"Collection '{collection_name}' 创建成功")

# 验证
collections = client.list_collections()
print(f"创建后: {collections}")
# 输出: ['docs']

# =============================================
# 7. 删除 Collection
# =============================================
client.drop_collection(collection_name)
print(f"Collection '{collection_name}' 已删除")

# 验证
collections = client.list_collections()
print(f"删除后: {collections}")
# 输出: []

# =============================================
# 8. 删除数据库
# =============================================
# 注意：必须先确保数据库下没有 Collection
client.drop_database(db_name)
print(f"数据库 '{db_name}' 已删除")

# 验证
existing_databases = client.list_databases()
print(f"删除后: {existing_databases}")
# 输出: ['default']

各操作间的安全性说明

# 创建数据库 —— 建议加存在性判断
if db_name not in client.list_databases():
    client.create_database(db_name)

# 删除数据库 —— 不需要判断，不存在时静默结束
client.drop_database(db_name)  # 存在则删，不存在也不报错

# 删除 Collection —— 同样不需要判断
client.drop_collection(collection_name)  # 幂等操作

⚠️ 常见问题与避坑指南

Milvus 未启动时报错：执行任何操作前确保 Docker 中 milvus-standalone 容器处于 Running 状态。
数据库无法删除：若数据库下有 Collection，drop_database 会失败。必须先 drop_collection 清空所有集合，再删除数据库。
dimension 必须与 Embedding 模型一致：如果用 BGE 模型（1024 维）创建 Collection，但后续用 text-embedding-3-large（3072 维）插入数据，会报维度不匹配错误。
切换数据库后才能操作 Collection：list_collections()、create_collection() 等操作依赖当前 use_database() 的上下文，忘记切换会导致找不到预期的集合。
端口号核对：Milvus Standalone 默认端口 19530，修改过 docker-compose.yml 端口映射的需相应调整。
Collection 名称规范：建议使用小写字母和下划线，避免特殊字符。

💡 个人总结与延伸

Milvus 的 Python SDK (pymilvus) 提供了直观的 ORM 风格 API，client.list_databases() / client.create_database() 等方法命名清晰，学习曲线平缓。
DDL 操作是后续 DML（数据插入/查询）的基础，必须先创建好 Database 和 Collection 才能写入数据。
Collection 创建时确定的 dimension 和 metric_type 是不可变的（或需要重建），因此在项目初期就要明确使用哪个 Embedding 模型。
下一步将学习 DML 操作：向 Collection 中插入向量数据、进行相似度检索。