> ## 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.

# 使用 OpenSearch 存储

`opensearch` 后端使用 OpenSearch 作为向量存储。知识文本先经 embedding 模型向量化，再通过 LlamaIndex 写入 OpenSearch，检索时按相似度召回。

## 何时使用

* 已有 OpenSearch 集群，希望自建向量检索；
* 需要持久化、可跨进程与多实例共享，并对索引与检索有完全掌控。

## 依赖

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

## 使用示例

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

# index 需为小写，仅含 a-z0-9_-. 且不以 _ 或 - 开头
kb = KnowledgeBase(backend="opensearch", index="company_faq")
kb.add_from_text("公司的标准年假为每年 15 天，入职满一年起享受。")

agent = Agent(
    name="demo",
    instruction="回答用户问题，必要时用 `load_knowledgebase` 工具检索知识库。",
    knowledgebase=kb,
)
```

也可以通过 `backend_config` 显式传入连接与 embedding 配置：

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

kb = KnowledgeBase(
    backend="opensearch",
    index="company_faq",
    backend_config={
        "index": "company_faq",
        "opensearch_config": OpensearchConfig(
            host="localhost",
            port=9200,
            username="admin",
            password="admin",
            use_ssl=True,
            cert_path="/path/to/ca.pem",
        ),
    },
)
```

## 参数

### 构造参数

`backend_config` 支持以下配置项：

| 参数 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- |
| `index` | `str` | 无默认，由 `KnowledgeBase` 传入 | 知识库索引名，须符合 OpenSearch 命名规则。 |
| `opensearch_config` | `OpensearchConfig` | 自动从 `DATABASE_OPENSEARCH_*` 环境变量读取 | OpenSearch 连接配置。 |
| `embedding_config` | `EmbeddingModelConfig` | 自动从 `MODEL_EMBEDDING_*` 环境变量读取 | embedding 模型配置。 |

### OpenSearch 连接配置

`opensearch_config` 为 `OpensearchConfig`，环境变量前缀 `DATABASE_OPENSEARCH_`：

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `host` | `DATABASE_OPENSEARCH_HOST` | `str` | `""` | OpenSearch 主机地址。 |
| `port` | `DATABASE_OPENSEARCH_PORT` | `int` | `9200` | 端口。 |
| `use_ssl` | `DATABASE_OPENSEARCH_USE_SSL` | `bool` | `true` | 是否启用 SSL。 |
| `username` | `DATABASE_OPENSEARCH_USERNAME` | `str` | `""` | 用户名。 |
| `password` | `DATABASE_OPENSEARCH_PASSWORD` | `str` | `""` | 密码。 |
| `cert_path` | `DATABASE_OPENSEARCH_CERT_PATH` | `str` | `""` | CA 证书路径。为空时不校验证书，存在安全风险并会告警。 |
| `secret_token` | `DATABASE_OPENSEARCH_SECRET_TOKEN` | `str` | `""` | STS 临时凭证令牌。 |

### embedding 配置

`embedding_config` 为 `EmbeddingModelConfig`，环境变量前缀 `MODEL_EMBEDDING_`：

| 配置项 | 环境变量 | 类型 | 默认值 | 说明 |
| :- | :- | :- | :- | :- |
| `name` | `MODEL_EMBEDDING_NAME` | `str` | `doubao-embedding-vision-250615` | embedding 模型名。 |
| `dim` | `MODEL_EMBEDDING_DIM` | `int` | `2048` | embedding 向量维度，用于创建索引的向量字段。 |
| `api_base` | `MODEL_EMBEDDING_API_BASE` | `str` | `https://ark.cn-beijing.volces.com/api/v3/` | embedding 服务的 API 地址。 |
| `api_key` | `MODEL_EMBEDDING_API_KEY` | `str` | 依次回退到 `MODEL_AGENT_API_KEY` 或自动获取的 Ark 令牌 | 访问 embedding 服务的密钥。 |

## 环境变量配置

```bash lines theme={null}
# OpenSearch 连接
export DATABASE_OPENSEARCH_HOST="localhost"
export DATABASE_OPENSEARCH_PORT=9200
export DATABASE_OPENSEARCH_USERNAME="admin"
export DATABASE_OPENSEARCH_PASSWORD="admin"
export DATABASE_OPENSEARCH_USE_SSL=true
export DATABASE_OPENSEARCH_CERT_PATH="/path/to/ca.pem"

# embedding 模型
export MODEL_EMBEDDING_NAME="doubao-embedding-vision-250615"
export MODEL_EMBEDDING_DIM=2048
export MODEL_EMBEDDING_API_KEY="your-ark-api-key"
```

<Warning>
  `index` 必须符合 OpenSearch 命名规则：全小写，仅含 `a-z0-9_-.`，且不以 `_` 或 `-` 开头，否则会报错。生产环境请配置 `cert_path` 以启用证书校验，避免安全风险。
</Warning>