> ## 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、需要持久化和多实例共享知识的场景。`KnowledgeBase.index` 对应 Milvus collection 名称。

## 前置条件

安装包含 Milvus 和 LlamaIndex 集成的扩展依赖，并准备可访问的 Milvus 实例：

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

Milvus 后端需要 embedding 模型。下面的环境变量同时配置 Milvus 连接与 embedding 模型：

```bash lines theme={null}
export DATABASE_MILVUS_URI="http://127.0.0.1:19530"
export DATABASE_MILVUS_TOKEN="${MILVUS_TOKEN}"
export MODEL_EMBEDDING_NAME="doubao-embedding-text-240715"
export MODEL_EMBEDDING_DIM="2560"
export MODEL_EMBEDDING_API_KEY="${ARK_API_KEY}"
```

也可以不设置 `DATABASE_MILVUS_TOKEN`，改用 `DATABASE_MILVUS_USER` 与 `DATABASE_MILVUS_PASSWORD`。Token 的优先级高于用户名和密码。

## 使用示例

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

knowledgebase = KnowledgeBase(
    backend="milvus",
    index="company_faq",
    top_k=3,
)

knowledgebase.add_from_text(
    [
        "标准年假为每年 15 天。",
        "员工经主管批准后每周最多远程办公 2 天。",
    ]
)

for entry in knowledgebase.search("每周可以远程办公几天？"):
    print(entry.content)
```

## 参数

通过 `KnowledgeBase(backend="milvus", backend_config={...})` 传入后端参数。未传入 `backend_config` 时，VeADK 会从对应环境变量读取连接配置，并使用全局 embedding 配置。

| 参数 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `index` | 无 | `str` | 必填 | Milvus collection 名称。必须以字母或下划线开头，只能包含字母、数字和下划线，最长 255 个字符。通常通过 `KnowledgeBase.index` 传入。 |
| `milvus_config.uri` | `DATABASE_MILVUS_URI` | `str` | `""` | Milvus 服务 URI，也可使用 Milvus Lite 支持的本地文件路径。必须配置。 |
| `milvus_config.token` | `DATABASE_MILVUS_TOKEN` | `str` | `""` | Milvus Token。设置后优先于用户名和密码。 |
| `milvus_config.user` | `DATABASE_MILVUS_USER` | `str` | `""` | Milvus 用户名，与 `password` 配合使用。 |
| `milvus_config.password` | `DATABASE_MILVUS_PASSWORD` | `str` | `""` | Milvus 密码，与 `user` 配合使用。 |
| `milvus_config.db_name` | `DATABASE_MILVUS_DB_NAME` | `str` | `"default"` | Milvus 数据库名称。 |
| `milvus_config.overwrite` | `DATABASE_MILVUS_OVERWRITE` | `bool` | `False` | 初始化时是否覆盖同名 collection。 |
| `milvus_config.timeout` | `DATABASE_MILVUS_TIMEOUT` | `float \| None` | `None` | Milvus 请求超时时间，单位为秒。 |
| `milvus_config.output_fields` | `DATABASE_MILVUS_OUTPUT_FIELDS` | `list[str] \| str` | `[]` | 检索时返回的额外字段。环境变量可写为逗号分隔字符串或 JSON 字符串数组。 |
| `embedding_config` | `MODEL_EMBEDDING_*` | `EmbeddingModelConfig` | 全局 embedding 配置 | 模型名称、维度、API 地址和 API Key。 |

<Warning>
  `DATABASE_MILVUS_OVERWRITE=true` 会在初始化时覆盖同名 collection，原有知识数据可能丢失。仅在确认不需要保留现有数据时启用。
</Warning>

除 `search(query, top_k)` 外，该后端支持 `add_from_text`、`add_from_files` 与 `add_from_directory`。文件和目录导入会按文件类型切分内容，再写入同一个 collection。