proofdb/scriptdoc/setup_opensearch.md

OpenSearch 索引初始化脚本

脚本路径

scripts/setup_opensearch.php

脚本作用

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

当前版本会确保：

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

运行前提

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

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

OPENSEARCH_SSL_VERIFY=false php scripts/setup_opensearch.php

运行命令

php scripts/setup_opensearch.php

成功输出示例

OpenSearch chunk index initialized: proofdb_chunks
Vector dimensions: 2048

适用场景

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

常见失败信号

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