技能名称: alicloud-ai-search-opensearch
详细描述:
类别: provider

OpenSearch 向量搜索版

使用 ha3engine SDK 推送文档并执行 HA/SQL 搜索。本技能仅关注 API/SDK 的使用（不包含控制台操作步骤）。

前提条件

• - 安装 SDK（建议在虚拟环境中安装以避免 PEP 668 限制）：

bash
python3 -m venv .venv
. .venv/bin/activate
python -m pip install alibabacloud-ha3engine

• - 通过环境变量提供连接配置：

快速开始（推送 + 搜索）

python
import os
from alibabacloud_ha3engine import models, client
from Tea.exceptions import TeaException, RetryError

cfg = models.Config(
endpoint=os.getenv(OPENSEARCH_ENDPOINT),
instanceid=os.getenv(OPENSEARCHINSTANCE_ID),
protocol=http,
accessusername=os.getenv(OPENSEARCH_USERNAME),
accesspassword=os.getenv(OPENSEARCH_PASSWORD),
)
ha3 = client.Client(cfg)

def push_docs():
datasource = os.getenv(OPENSEARCHDATASOURCE)
pkfield = os.getenv(OPENSEARCHPK_FIELD, id)

documents = [
{fields: {id: 1, title: hello, content: world}, cmd: add},
{fields: {id: 2, title: faq, content: vector search}, cmd: add},
]
req = models.PushDocumentsRequestModel({}, documents)
return ha3.pushdocuments(datasource, pk_field, req)

def search_ha():
# HA 查询示例。根据需要替换集群/表名。
query_str = (
config=hit:5,format:json,qrs_chain:search
&&query=title:hello
&&cluster=general
)
haquery = models.SearchQuery(query=querystr)
req = models.SearchRequestModel({}, ha_query)
return ha3.search(req)

try:
print(push_docs().body)
print(search_ha())
except (TeaException, RetryError) as e:
print(e)

脚本快速开始

bash
python skills/ai/search/alicloud-ai-search-opensearch/scripts/quickstart.py

环境变量：

• - OPENSEARCHENDPOINT
• OPENSEARCHINSTANCEID
• OPENSEARCHUSERNAME
• OPENSEARCHPASSWORD
• OPENSEARCHDATASOURCE
• OPENSEARCHPKFIELD（可选，默认值为 id）
• OPENSEARCH_CLUSTER（可选，默认值为 general）

可选参数：--cluster、--hit、--query。

SQL 风格搜索

python
from alibabacloud_ha3engine import models

sql = select * from &&kvpair=trace:INFO;formatType:json
sql_query = models.SearchQuery(sql=sql)
req = models.SearchRequestModel({}, sql_query)
resp = ha3.search(req)
print(resp)

给 Claude Code/Codex 的注意事项

• - 使用 push_documents 进行添加/删除更新。
• 大型查询字符串（超过30KB）应使用 RESTful 搜索 API。
• HA 查询对于向量和关键词检索快速且灵活；SQL 有助于处理结构化数据。

错误处理

• - 认证错误：验证用户名/密码和实例访问权限。
• 推送时出现4xx错误：检查 schema 字段和 pk_field 是否对齐。
• 5xx错误：使用退避策略重试。

验证

bash
mkdir -p output/alicloud-ai-search-opensearch
for f in skills/ai/search/alicloud-ai-search-opensearch/scripts/*.py; do
python3 -m py_compile $f
done
echo pycompileok > output/alicloud-ai-search-opensearch/validate.txt

通过标准：命令退出码为0，并且 output/alicloud-ai-search-opensearch/validate.txt 已生成。

输出与证据

• - 将产物、命令输出和 API 响应摘要保存在 output/alicloud-ai-search-opensearch/ 目录下。
• 在证据文件中包含关键参数（区域/资源ID/时间范围）以确保可重现性。

工作流程

1) 确认用户意图、区域、标识符以及操作是只读还是修改性操作。
2) 首先执行一个最小的只读查询以验证连接和权限。
3) 使用明确的参数和有限的范围执行目标操作。
4) 验证结果并保存输出/证据文件。

参考资料

• - SDK 包：alibabacloud-ha3engine
• 演示：OpenSearch 文档中的数据推送和 HA/SQL 搜索演示

• - 来源列表：references/sources.md