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

# 使用 Milvus 存储

`milvus` 后端将知识片段向量化后写入 Milvus collection，适合已有 Milvus 服务或需要在本地使用 Milvus Lite 持久化数据的场景。`index` 对应 Milvus collection 名称。

## 前提条件

安装 VeADK 的扩展依赖，并准备可用的 embedding 模型：

```bash lines theme={null}
pip install "veadk-python[extensions]"
```

远程 Milvus 还需要准备服务地址和鉴权信息。本地验证可以把 `DATABASE_MILVUS_URI` 指向 Milvus Lite 数据文件。

## 使用 Milvus Lite

```bash lines theme={null}
export DATABASE_MILVUS_URI="./data/company_faq.db"
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"
```

```python lines theme={null}
from veadk import Agent
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(backend="milvus", index="company_faq")
kb.add_from_text("公司的标准年假为每年 15 天，入职满一年起享受。")

agent = Agent(
    name="company_assistant",
    instruction="优先使用知识库回答公司制度相关问题。",
    knowledgebase=kb,
)
```

首次运行会在 `./data/company_faq.db` 中创建数据。再次使用相同文件和 collection 名称时，可以检索已写入的内容。

## 连接远程 Milvus

```bash lines theme={null}
export DATABASE_MILVUS_URI="https://milvus.example.com:19530"
export DATABASE_MILVUS_TOKEN="your-milvus-token"
export DATABASE_MILVUS_DB_NAME="default"
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"
```

也可以通过公开配置对象传入连接参数：

```python lines theme={null}
from veadk.configs.database_configs import MilvusConfig
from veadk.knowledgebase import KnowledgeBase

kb = KnowledgeBase(
    backend="milvus",
    backend_config={
        "index": "company_faq",
        "milvus_config": MilvusConfig(
            uri="https://milvus.example.com:19530",
            token="your-milvus-token",
            db_name="default",
        ),
    },
)
```

凭证应通过环境变量或密钥管理服务注入，不要把真实 token 提交到代码仓库。

## 参数

### 构造参数

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `index` | `str` | 无 | Milvus collection 名称。必须以字母或下划线开头，只能包含字母、数字和下划线，最长 255 个字符。 |
| `milvus_config` | `MilvusConfig` | 从 `DATABASE_MILVUS_*` 环境变量读取 | Milvus 连接与 collection 配置。 |
| `embedding_config` | `EmbeddingModelConfig` | 从 `MODEL_EMBEDDING_*` 环境变量读取 | embedding 模型配置。 |

### Milvus 配置

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `uri` | `DATABASE_MILVUS_URI` | `str` | `""` | Milvus Lite 文件路径或远程 Milvus URI。必须配置。 |
| `token` | `DATABASE_MILVUS_TOKEN` | `str` | `""` | 鉴权 token。配置后优先于用户名和密码。 |
| `user` | `DATABASE_MILVUS_USER` | `str` | `""` | 用户名；仅在同时提供 `password` 且未提供 `token` 时使用。 |
| `password` | `DATABASE_MILVUS_PASSWORD` | `str` | `""` | 密码；仅在同时提供 `user` 且未提供 `token` 时使用。 |
| `db_name` | `DATABASE_MILVUS_DB_NAME` | `str` | `default` | 数据库名称。 |
| `overwrite` | `DATABASE_MILVUS_OVERWRITE` | `bool` | `false` | 初始化时是否覆盖同名 collection。 |
| `timeout` | `DATABASE_MILVUS_TIMEOUT` | `float \| None` | `None` | 连接和请求超时时间，单位取决于 Milvus 客户端。 |
| `output_fields` | `DATABASE_MILVUS_OUTPUT_FIELDS` | `list[str] \| str` | `[]` | 检索时返回的附加字段；环境变量可使用逗号分隔字符串或 JSON 字符串数组。 |

<Warning>
  将 `DATABASE_MILVUS_OVERWRITE` 设为 `true` 会覆盖同名 collection 及其中的数据。仅在确认数据可重建时使用。
</Warning>

### embedding 配置

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `name` | `MODEL_EMBEDDING_NAME` | `str` | `doubao-embedding-vision-250615` | embedding 模型名称。 |
| `dim` | `MODEL_EMBEDDING_DIM` | `int` | `2048` | 向量维度，必须与模型输出维度一致。 |
| `api_base` | `MODEL_EMBEDDING_API_BASE` | `str` | `https://ark.cn-beijing.volces.com/api/v3/` | embedding 服务地址。 |
| `api_key` | `MODEL_EMBEDDING_API_KEY` | `str` | 回退到 `MODEL_AGENT_API_KEY` 或自动获取的火山方舟令牌 | embedding 服务凭证。 |