# OpenSearch 索引初始化脚本

## 脚本路径

```text
scripts/setup_opensearch.php
```

## 脚本作用

创建或确认 Proof DB 使用的 OpenSearch chunk 索引，并同步缺失的增量 mapping 字段。

当前版本会确保：

- `proofdb_chunks` 索引存在。
- BM25 全文字段 mapping 已建立。
- 已存在索引上的缺失字段 mapping 会被补齐，例如后续新增的 `summary`。
- `embedding` 字段为 `knn_vector`。
- 向量维度与当前配置一致。

## 运行前提

- OpenSearch 服务已经启动。
- 当前环境中的 OpenSearch 配置可用。
- 项目依赖已安装完成。
- 从项目根目录执行命令。

如果本地 OpenSearch 使用 HTTPS 且证书是自签名：

```bash
OPENSEARCH_SSL_VERIFY=false php scripts/setup_opensearch.php
```

## 运行命令

```bash
php scripts/setup_opensearch.php
```

## 成功输出示例

```text
OpenSearch chunk index initialized: proofdb_chunks
Vector dimensions: 2048
```

## 适用场景

- OpenSearch 首次初始化。
- `proofdb_chunks` 被删除后重建。
- 增加了新的文档字段，例如 `summary`。
- 调整了索引 mapping 或向量维度后重新准备索引。

## 常见失败信号

- `NoNodesAvailableException`
  说明 host、协议、端口、SSL 校验或服务状态不对。
- 鉴权失败
  说明 `OPENSEARCH_USERNAME` / `OPENSEARCH_PASSWORD` 不正确。