> ## Documentation Index
> Fetch the complete documentation index at: https://docs.textin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Zilliz Cloud

> 配置 Zilliz Cloud 云服务，提供托管的向量数据库服务

## Zilliz Cloud

Zilliz Cloud 是 Milvus 的云服务版本，提供托管的向量数据库服务。

### 参数说明

| 参数                | 类型        | 必填 | 说明                                 |
| ----------------- | --------- | -- | ---------------------------------- |
| `type`            | `string`  | 是  | 固定为 `"zilliz"`                     |
| `db_path`         | `string`  | 是  | Zilliz Cloud 连接地址                  |
| `collection_name` | `string`  | 是  | 集合（Collection）名称                   |
| `dimension`       | `integer` | 是  | 向量维度，必须与 embed 模型维度一致（当前为 1024）    |
| `api_key`         | `string`  | 否  | Zilliz Cloud API Key（与 token 二选一）  |
| `token`           | `string`  | 否  | Zilliz Cloud Token（与 api\_key 二选一） |

### 如何获取鉴权参数

1. **注册 Zilliz Cloud 账号**：
   * 访问 [Zilliz Cloud 官网](https://zilliz.com/cloud)
   * 注册并登录账号

2. **创建集群**：
   * 在 Zilliz Cloud 控制台创建新的集群
   * 选择合适的地域和规格
   * 等待集群创建完成

3. **获取连接信息**：
   * 在集群详情页查看"连接地址"（Endpoint）
   * 格式：`https://xxxxxxx.serverless.xxxxxxx.cloud.zilliz.com.cn`

4. **获取 API Key**：
   * 进入"API Keys"页面
   * 创建新的 API Key 或使用现有 Key
   * 保存 API Key 值（注意：API Key 只显示一次，请妥善保存）

5. **创建集合**（可选）：
   * Pipeline 会自动创建集合，但您也可以预先在控制台创建
   * 确保集合的向量维度与 embed 模型一致（1024 维）

### 配置示例

使用 API Key：

```python theme={null}
from xparse_client import MilvusDestination

destination = MilvusDestination(
    db_path='https://xxxxxxx.serverless.xxxxxxx.cloud.zilliz.com.cn',  # Zilliz Cloud 连接地址
    collection_name='my_collection',      # 集合名称
    dimension=1024,                      # 向量维度
    api_key='your-zilliz-api-key'        # Zilliz Cloud API Key
)
```

或使用 token：

```python theme={null}
from xparse_client import MilvusDestination

destination = MilvusDestination(
    db_path='https://xxxxxxx.serverless.xxxxxxx.cloud.zilliz.com.cn',
    collection_name='my_collection',
    dimension=1024,
    token='your-zilliz-token'            # 使用 token 替代 api_key
)
```

### 使用示例

```python theme={null}
from xparse_client import MilvusDestination, Pipeline

destination = MilvusDestination(
    db_path='https://xxxxxxx.serverless.xxxxxxx.cloud.zilliz.com.cn',
    collection_name='documents',
    dimension=1024,
    api_key='your-zilliz-api-key'
)

# ... 其他配置

pipeline = Pipeline(
    source=source,
    destination=destination,
    # ...其他配置
)
pipeline.run()
```

### 数据 Schema

Zilliz Cloud 与本地 Milvus 共享相同的 Schema：

| 字段名          | 类型                  | 说明           |
| ------------ | ------------------- | ------------ |
| `element_id` | VARCHAR(128)        | 元素唯一标识符（主键）  |
| `embeddings` | FLOAT\_VECTOR(1024) | 向量嵌入（1024 维） |
| `text`       | VARCHAR(65535)      | 元素文本内容       |
| `record_id`  | VARCHAR(128)        | 记录 ID        |
| `metadata`   | JSON                | 元数据信息（动态字段）  |

### 向量检索示例

```python theme={null}
from pymilvus import MilvusClient

client = MilvusClient(
    uri='https://xxxxxxx.serverless.xxxxxxx.cloud.zilliz.com.cn',
    token='your-zilliz-api-key'  # 或 token
)

query_vector = [0.1, 0.2, 0.3, ...]  # 1024 维向量

results = client.search(
    collection_name='documents',
    data=[query_vector],
    limit=5,
    search_params={"metric_type": "COSINE", "params": {"nprobe": 10}},
    output_fields=['text', 'metadata']
)

for result in results[0]:
    print(f"相似度: {1 - result['distance']:.4f}")
    print(f"文本: {result['entity']['text'][:100]}...")
```

### 参考文档

* [Zilliz Cloud 文档](https://docs.zilliz.com/docs)