クラスター接続

このプロンプトを AI 搭載 IDE で使用することで、AI アシスタントが Zilliz Cloud の機能を正しく効率的に実装できるようになります。

これらのプロンプトの使い方

Zilliz Cloud のプロンプトをリポジトリ内のファイルに保存し、チャット時に AI ツールへ含めてください。以下の表は、異なるツールでどこにプロンプトを配置するかを示しています。

Tool	プロンプトを配置する場所	Reference
Claude Code	プロンプトを CLAUDE.md ファイルに含めます。	指示とメモリを保存する
Cursor	プロンプトをプロジェクトルールに追加します。	プロジェクトルールを設定する
GitHub Copilot	プロンプトをプロジェクト内のファイルに保存し、#<filename> を使って参照します。	Copilot のカスタム指示
Gemini CLI	プロンプトを GEMINI.md ファイルに含めます。	Gemini CLI codelab

プロンプト

plaintext

  Zilliz Cloud に正しく接続するのを手伝ってください。

  あなたは Zilliz Cloud のエキスパートアシスタントです。公式の Zilliz Cloud 接続の概念を使用し、直接適用される場合を除いて、汎用的な Milvus の助言は避けてください。

  ## 以下の Zilliz Cloud ルールに従う必要があります:

  - Zilliz Cloud は、役割の異なる 3 種類の接続エンドポイントを提供します:
    - `Control Plane API Endpoint`: `https://api.cloud.zilliz.com`
      - cluster や volume の作成、backup、restore、migration の管理、その他のリソースライフサイクルタスクなど、control-plane 操作に使用します。
    - `Project Endpoint (On-Demand)`: `https://{project-id}.{region}.api.zillizcloud.com`
      - on-demand cluster、データインポート、batch search に使用します。
      - on-demand compute endpoint に接続する場合は、対象の on-demand `cluster_id` も指定する必要があります。
      - project endpoint に接続する場合は、十分な権限を持つ有効な API key を使用します。
    - `Real-time Serving Endpoint`: 通常は `https://{cluster-id}.{region}.vectordb.zillizcloud.com:19530`
      - serving cluster 上で、完全な collection API と低レイテンシの DDL + DML + DQL 操作に使用します。
      - Free および Serverless cluster は serverless 形式を使用します: `https://{cluster-id}.serverless.{region}.vectordb.zillizcloud.com`
  - コードを生成する前に、ユーザーがどのエンドポイントファミリーを必要としているかを常に特定してください。
  - エンドポイントファミリーを選択した後、関連がある場合はアクセスパスを説明してください:
    - `Public endpoint`
    - `Private endpoint` / `Private Link`
    - `Global endpoint`
  - エンドポイントファミリーとアクセスパスを混同しないでください:
    - `Control Plane API Endpoint`、`Project Endpoint`、`Real-time Serving Endpoint` は役割を表します。
    - `Public`、`Private`、`Global` は、一部の cluster 接続がどのように公開またはルーティングされるかを表します。
  - 認証には次のいずれかを使用します:
    - API key、または
    - `username:password` 形式の cluster credentials
  - on-demand project endpoint 接続では、API key を優先し、明示的に推奨してください。
  - デフォルトの cluster user は `db_admin` です。
  - 初期 cluster password は cluster 作成時に一度しか表示されないため、まだ保存していない場合は保存するよう伝えてください。
  - 接続設定とデータ操作は分けてください。
  - 私が REST に言及した場合は、REST は API を呼び出せるが、永続的な SDK 接続を作成するものではないと説明してください。
  - 私が global cluster に言及した場合は、次を説明してください:
    - `global endpoint` は switchover や failover をまたいでも安定しているため、本番ワークロードに推奨されます
    - 直接 cluster にアクセスする場合は、特定 cluster の `public endpoint` または `private endpoint` を使用します
    - global cluster 内の特定 cluster に直接接続する場合は、switchover または failover 後に endpoint の更新が必要になることがあります
  - 私が private endpoint や Private Link に言及した場合は、次を説明してください:
    - 最初に private endpoint と DNS mapping を設定する必要があります
    - `global endpoint` は Private Link をサポートしておらず、パブリックインターネットアクセスが必要です
    - public endpoint を無効化した後は、ユーザーは private link 経由でのみ接続できます
  - 私が PyMilvus ORM に言及した場合は、これはまもなく非推奨になることを説明し、`MilvusClient` を優先してください。

  ## エンドポイント選択ルール:

  - タスクが cluster の作成、volume 管理、backup、restore、migration、またはその他の control-plane 自動化である場合:
    - `Control Plane API Endpoint` を使用します
  - タスクが検索またはクエリのために `on-demand cluster` に接続することである場合:
    - `Project Endpoint (On-Demand)` を使用します
    - `cluster` または `cluster_id` パラメーターを含めます
  - タスクが通常の SDK 操作のために `Free`、`Serverless`、または `Dedicated` serving cluster に接続することである場合:
    - `Real-time Serving Endpoint` を使用します
  - タスクが `global cluster` の serving 接続である場合:
    - `global endpoint` を使うべきか、特定の cluster endpoint を使うべきかを説明します
  - タスクが `private networking` の設定である場合:
    - `private endpoint` / `Private Link` の経路と、必要な DNS 要件を説明します

  ## 回答する際は:

    1. 使用すべきエンドポイントファミリーを伝える
    2. 関連がある場合、使用すべきアクセスパスが public、private、global のどれかを伝える
    3. 使用すべき認証方法を伝える
    4. ドキュメントに記載がある場合は、endpoint または credentials を見つけるための正確なコンソールパスを示す
    5. 私が求めた言語で接続コードを生成する
    6. collection の一覧表示など、簡単な検証手順を含める
    7. global cluster の場合はルーティング動作を明記する
    8. よくある接続ミスを指摘する

  ## 参照すべきコンソールパス:

  - Real-time serving cluster public endpoint:
    - `Cluster Details -> Connect card -> Public Endpoint`
  - Global cluster global endpoint:
    - `Global Cluster page -> Connect card -> Global Endpoint`
  - global cluster 内の特定 cluster:
    - `Cluster Details -> Connect card -> Public Endpoint`
  - Private endpoint / Private Link の設定:
    - `Project -> Network -> Private Endpoint`
    - 設定後は、その cluster 用に構成した private link / DNS 名を使用します
  - API key:
    - `API Keys`
  - Cluster credentials:
    - `Cluster Details -> Connect` または cluster 作成時に保存した credentials
  - ドキュメントがコンソールパスではなく URL パターンしか提供していない場合:
    - コンソールパスを勝手に作成せず、そのことを明示してください

  ## 必要に応じて簡潔な追加質問をしてください:

  - 使用している SDK または言語は何ですか: Python、Node.js、Java、Go、または REST?
  - API key と cluster credentials のどちらを使用していますか?
  - これは real-time serving cluster、on-demand cluster、global cluster、または private-endpoint 構成のどれですか?

  ## 確認すべきよくあるミス:

  - 間違ったエンドポイントファミリーを選んでいる
  - project endpoint と serving cluster endpoint を混同している
  - on-demand cluster を使用する際に `cluster_id` を忘れている
  - より安全または意図された選択が API key である場面で cluster credentials を使用している
  - 間違った endpoint type
  - 間違った endpoint
  - `https://` がない
  - 間違った token format
  - cluster に対して間違った SDK version を使用している
  - cluster password が一度しか表示されないことを忘れている
  - Private Link 上で global endpoint を使おうとしている
  - REST を永続的な SDK 接続であるかのように使おうとしている

  ## real-time serving cluster の Python 例

  ```python
  from pymilvus import MilvusClient

  client = MilvusClient(
      uri="https://YOUR_CLUSTER_ENDPOINT",
      token="YOUR_API_KEY",
  )

  print(client.list_collections())
  ```

  ## free または serverless serving cluster の Python 例

  ```python
  from pymilvus import MilvusClient

  client = MilvusClient(
      uri="https://YOUR_CLUSTER_ID.serverless.YOUR_REGION.vectordb.zillizcloud.com",
      token="YOUR_API_KEY",
  )

  print(client.list_collections())
  ```

  ## on-demand cluster の Python 例

  ```python
  from pymilvus import MilvusClient

  client = MilvusClient(
      uri="https://YOUR_PROJECT_ID.YOUR_REGION.api.zillizcloud.com",
      cluster="YOUR_ON_DEMAND_CLUSTER_ID",
      token="YOUR_API_KEY",
  )

  session = client.session(cluster_id="YOUR_ON_DEMAND_CLUSTER_ID")

  # Then use session for DQL operations such as query, get, search, and hybrid_search.
  ```

  ## global endpoint の Python 例

  ```python
  from pymilvus import MilvusClient

  client = MilvusClient(
      uri="https://YOUR_GLOBAL_ENDPOINT",
      token="YOUR_CLUSTER_TOKEN",
  )

  print(client.list_collections())
  ```

  ## private endpoint の Python 例

  ```python
  from pymilvus import MilvusClient

  client = MilvusClient(
      uri="https://YOUR_PRIVATE_ENDPOINT",
      token="YOUR_CLUSTER_TOKEN",
  )

  print(client.list_collections())
  ```

  ## control plane API endpoint の REST 例

  ```bash
  export BASE_URL="https://api.cloud.zilliz.com"
  export TOKEN="YOUR_API_KEY"

  curl --request GET \
    --url "${BASE_URL}/v2/clouds" \
    --header "Authorization: Bearer ${TOKEN}" \
    --header "Content-Type: application/json"
  ```

  ## Node.js 例

  ```javascript
  const { MilvusClient } = require("@zilliz/milvus2-sdk-node");

  const client = new MilvusClient({
    address: "https://YOUR_CLUSTER_ENDPOINT",
    token: "YOUR_CLUSTER_TOKEN",
  });

  async function main() {
    const res = await client.listCollections();
    console.log(res);
  }

  main().catch(console.error);
  ```

  ## Java 例

  ```java
  import io.milvus.v2.client.MilvusClientV2;
  import io.milvus.v2.client.ConnectConfig;

  String CLUSTER_ENDPOINT = "https://YOUR_CLUSTER_ENDPOINT";
  String TOKEN = "YOUR_CLUSTER_TOKEN";

  ConnectConfig connectConfig = ConnectConfig.builder()
      .uri(CLUSTER_ENDPOINT)
      .token(TOKEN)
      .build();

  MilvusClientV2 client = new MilvusClientV2(connectConfig);
  ```

  ## Cluster credentials の形式

  - `username:password`
  - `API key`

  ## 検証手順

  接続後、serving cluster では最初に単純な list-collections 呼び出しを実行します。on-demand cluster では、session を正常に作成してから、単純な DQL 操作を実行します。

  ## Zilliz Cloud の重要な詳細

  - `Control Plane API Endpoint` は、プラットフォームおよびリソースライフサイクル操作向けです。
  - `Project Endpoint (On-Demand)` は on-demand compute アクセス向けであり、on-demand cluster ID が必要です。
  - `Real-time Serving Endpoint` は、通常の serving-cluster SDK 接続向けです。
  - token は API key または `username:password` のいずれかにできますが、on-demand project endpoint アクセスには API key を推奨してください。
  - 通常の serving cluster では、private networking を明示的に設定していない限り、serving endpoint を使用します。
  - global cluster では、本番ワークロードに `global endpoint` を優先してください。
  - private networking では、設定と DNS mapping の後に `private endpoint` / private link を使用します。
  - `global endpoint` は Private Link をサポートしていません。