alicloud-ai-search-opensearch

Category: プロバイダー

OpenSearch ベクトル検索エディション

ha3engine SDK を使用してドキュメントをプッシュし、HA/SQL 検索を実行します。このスキルでは API/SDK の使用方法のみを扱います（コンソールでの手順はありません）。

前提条件

• SDK をインストールします（PEP 668 の制限を避けるため、venv の使用を推奨します）。

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

• 環境変数で接続設定を指定します。
  • OPENSEARCH_ENDPOINT（API ドメイン）
  • OPENSEARCH_INSTANCE_ID
  • OPENSEARCH_USERNAME
  • OPENSEARCH_PASSWORD
  • OPENSEARCH_DATASOURCE（データソース名）
  • OPENSEARCH_PK_FIELD（主キーのフィールド名）

クイックスタート（プッシュ＋検索）

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

cfg = models.Config(
    endpoint=os.getenv("OPENSEARCH_ENDPOINT"),
    instance_id=os.getenv("OPENSEARCH_INSTANCE_ID"),
    protocol="http",
    access_user_name=os.getenv("OPENSEARCH_USERNAME"),
    access_pass_word=os.getenv("OPENSEARCH_PASSWORD"),
)
ha3 = client.Client(cfg)

def push_docs():
    data_source = os.getenv("OPENSEARCH_DATASOURCE")
    pk_field = os.getenv("OPENSEARCH_PK_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.push_documents(data_source, pk_field, req)


def search_ha():
    # HA query example. Replace cluster/table names as needed.
    query_str = (
        "config=hit:5,format:json,qrs_chain:search"
        "&&query=title:hello"
        "&&cluster=general"
    )
    ha_query = models.SearchQuery(query=query_str)
    req = models.SearchRequestModel({}, ha_query)
    return ha3.search(req)

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

スクリプトのクイックスタート

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

環境変数：

• OPENSEARCH_ENDPOINT
• OPENSEARCH_INSTANCE_ID
• OPENSEARCH_USERNAME
• OPENSEARCH_PASSWORD
• OPENSEARCH_DATASOURCE
• OPENSEARCH_PK_FIELD（任意、デフォルトは id）
• OPENSEARCH_CLUSTER（任意、デフォルトは general）

任意の引数：--cluster、--hit、--query。

SQL 形式の検索

from alibabacloud_ha3engine import models

sql = "select * from <indexTableName>&&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 エラー：スキーマのフィールドと pk_field の整合性を確認してください。
• 5xx エラー：バックオフを設けて再試行してください。

検証

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 "py_compile_ok" > output/alicloud-ai-search-opensearch/validate.txt

合格基準：コマンドが 0 で終了し、output/alicloud-ai-search-opensearch/validate.txt が生成されること。

出力と証跡

• 成果物、コマンド出力、API レスポンスの概要を output/alicloud-ai-search-opensearch/ に保存します。
• 再現性を確保するため、証跡ファイルに主要なパラメーター（リージョン／リソース ID／時間範囲）を含めてください。

ワークフロー

1. ユーザーの意図、リージョン、識別子、および操作が読み取り専用か変更を伴うかを確認します。
2. 接続と権限を確認するため、まず最小限の読み取り専用クエリを 1 つ実行します。
3. 明示的なパラメーターと限定された範囲で、対象の操作を実行します。
4. 結果を検証し、出力／証跡ファイルを保存します。

参考資料

• SDK パッケージ：alibabacloud-ha3engine

• デモ：OpenSearch ドキュメント内のデータプッシュおよび HA/SQL 検索のデモ

• ソース一覧：references/sources.md