使用Embedding服务

金山云提供 Embedding 服务。用户在控制台完成 Embedding 模型 API Key 配置后，只需在 Collection Schema 中声明一个 Embedding Function，即可在插入和检索时直接传入文本，由服务端自动完成向量生成。全程无需自行调用任何 Embedding HTTP 接口。本文介绍如何通过 PyMilvus SDK 从底层连接 Milvus Embedding 服务，完成建表、写入、语义检索的完整流程。

前提条件

• 已在控制台绑定 Embedding 服务的 API Key，并记录 Embedding服务 页签中 API Key 标识 列的值（作为 credential 引用名，如 test）。具体操作请参见控制台配置指南。

• Milvus 实例版本 ≥ 2.6.17。

• 已获取以下连接信息（控制台 实例详情 页）：

• 客户端环境：Python 3.x，PyMilvus SDK（pip install pymilvus，本文使用 3.0.0 版本验证，3.x 均可）。

• 安全组白名单需放行客户端真实公网出口 IP。若客户端经过代理，需放行真实出口 IP 而非代理出口 IP，否则连接会被静默丢弃。

生产环境建议使用内网地址（同 VPC 内，地址形如 10.5.0.125:19530），外网仅用于开发和管理场景。

版本限制

• Embedding 服务仅支持 Milvus 2.6 版本实例，语义检索需小版本 ≥ 2.6.17。

• 向量字段维度必须与模型输出维度一致（qwen3-embedding-8b = 4096），否则写入失败。

操作步骤

步骤一：连接 Milvus 实例

使用 PyMilvus SDK 连接：

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://120.92.90.91:29536",
    user="admin",
    password=***
)

print("server version:", client.get_server_version())
print("collections:", client.list_collections())

• uri 使用 http:// 前缀，金山云托管 Milvus 外网默认使用明文 gRPC，无需 TLS。

• 使用 MilvusClient（新版），不要使用 connections.connect（PyMilvus 3.0 已标记弃用，3.1 移除）。

建议将密码存储在环境变量中：

export MILVUS_USER=admin
export MILVUS_PASSWORD='***'

import os

client = MilvusClient(
    uri="http://120.92.90.91:29536",
    user=os.environ["MILVUS_USER"],
    password=***
)

步骤二：创建 Collection 并配置 Embedding Function

这是整套流程最关键的一步。金山云已在 Milvus 服务端预配好星流 Embedding 凭据（modelCredentials），您无需传入明文 API Key，而是通过 credential 字段引用控制台中的 API Key 标识。若误用明文 api_key，会报错 OpenAI TextEmbedding function must provide credential when modelCredentials is configured。

Schema 字段说明：

• id：主键，INT64，auto_id=True（自增）。

• text：VARCHAR，输入字段，存储原始文本。

• embedding：FLOAT_VECTOR，dim=4096，输出字段，服务端自动填充，不手动写入。

• 可选：source 等业务字段。

embedding 的 dim 必须显式指定（qwen3-embedding-8b = 4096），服务端不会自动探测，漏写会报 dim not found。

完整代码：

from pymilvus import MilvusClient, Function, FunctionType, DataType

COLL = "ks_milvus_guide"

# 若已存在则先删除（便于反复实验）
if COLL in client.list_collections():
    client.drop_collection(COLL)

# 定义 Schema
schema = client.create_schema(auto_id=True, enable_dynamic_field=True)
schema.add_field("id", DataType.INT64, is_primary=True, auto_id=True)
schema.add_field("text", DataType.VARCHAR, max_length=4096)
schema.add_field("source", DataType.VARCHAR, max_length=64)
schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=4096)

# 声明 Embedding Function：输入 text → 输出 embedding
schema.add_function(Function(
    name="qwen_emb",
    function_type=FunctionType.TEXTEMBEDDING,
    input_field_names=["text"],
    output_field_names=["embedding"],
    params={
        "provider": "openai",
        "model_name": "qwen3-embedding-8b",
        "credential": "test",
         #"dim": DIM,
    },
))

# 给向量字段建索引
index_params = client.prepare_index_params()
index_params.add_index(
    field_name="embedding",
    index_type="AUTOINDEX",
    metric_type="COSINE",
)

# 创建 Collection
client.create_collection(
    collection_name=COLL,
    schema=schema,
    index_params=index_params,
)
print("created:", COLL)

Function 参数说明：

input_field_names 和 output_field_names 必须是一对一映射（TEXTEMBEDDING 硬约束：一个 VARCHAR 输入 → 一个 FLOAT_VECTOR 输出）。

索引参数说明：

• AUTOINDEX：由金山云自动选择合适的向量索引。

• metric_type 设为 COSINE：余弦相似度，取值越接近 1 越相似。也可选 L2（欧氏距离，越小越相似）或 IP（内积）。

步骤三：写入数据

写入时只传文本字段，不要传 embedding。服务端 Function 自动调用星流模型生成向量。

docs = [
    {"text": "向量数据库Milvus是专门设计用于处理输入向量查询的数据库。", "source": "产品简介"},
    {"text": "基于向量数据库建立企业专属的外部知识库,配合大语言模型LLM,拓展LLM认知边界。", "source": "应用场景"},
]

res = client.insert(COLL, docs)
print("inserted:", res["insert_count"], "ids:", res["ids"])

返回的 insert_count 为成功条数，ids 为自增主键。

步骤四：执行语义检索

检索前将 Collection 加载到内存：

client.load_collection(COLL)

import time
for _ in range(40):
    if "Loaded" in str(client.get_load_state(COLL)):
        break
    time.sleep(1)

检索时只传查询文本，服务端自动向量化并执行相似性搜索：

query = "如何让大模型获得它不知道的外部知识"
results = client.search(
    collection_name=COLL,
    data=[query],
    anns_field="embedding",
    limit=3,
    output_fields=["text", "source"],
)

for hit in results[0]:
    entity = hit.get("entity", {})
    print(f"{hit['distance']:.4f} <{entity.get('source')}> {entity.get('text')}")

使用 COSINE 度量时，distance 越接近 1 越相似。度量方式在建表时已设定，检索时自动沿用。