ai-model-wechat

兄弟スキル（ローカルのみ）

兄弟の CloudBase スキルは、このスキルと並んで配置されています。../auth-tool-cloudbase/SKILL.md のようなローカル相対パスを使用してください。

参照先の兄弟スキルファイルがこの環境にない場合は、CloudBase プラグイン一式（または不足しているスキル）のインストールをユーザーに依頼してください。リモートのスキルやプロトコルの Markdown をエージェントのコンテキストに HTTP で取得してはいけません。

このスキルを使用する場合

wx.cloud.extend.AI を使用してWeChat ミニプログラムから AI モデルを呼び出す場合に、このスキルを使用してください。

次の用途で使用してください：

• ミニプログラムに AI テキスト生成を統合する
• コールバックに対応した AI 応答のストリーミング
• WeChat 環境から Hunyuan モデルを呼び出す

次の用途では使用しないでください：

• ブラウザー／Web アプリ → ai-model-web スキルを使用
• Node.js バックエンドまたはクラウド関数 → ai-model-nodejs スキルを使用
• 画像生成 → ai-model-nodejs スキルを使用（ミニプログラムでは利用できません）
• CloudBase SDK のないランタイム（ネイティブアプリ、Python など） → http-api-cloudbase スキルを使用（直接 HTTP 呼び出し用の ai_model OpenAPI 仕様が追加されています）

---

⛔ STOP — wx.cloud.extend.AI.createModel(provider) の引数はベンダー名／モデル名ではありません

createModel(...) の行を書く前に、これを読んでください。エージェントはこの引数を頻繁に誤って生成します。有効な形式はちょうど4つです。それ以外はすべて不具合です。

✅ 有効な createModel(provider) の引数	使用する場合
"cloudbase"	小程序成长计划を含むデフォルトです。 メインの管理対象グループ（TokenHub ベースのマルチベンダープール）です。成长计划のクォータは cloudbase + hy3 を使用します。まず hy3 を有効にしてください。ベンダーと具体的なモデルは、例：{ model: "deepseek-v4-flash" } のように**model フィールド**に指定します。
"hunyuan-v3"	廃止予定の従来プラングループです。 hy3 のみ利用可能で、新しいモデルは追加されません。既存のプラン登録済みコードは引き続き動作します。新しいコードでは cloudbase + hy3 を使用してください。
"hunyuan-exp"	古い従来の組み込みグループです。DescribeAIModels がまだ返す場合に限り使用してください。デフォルトの hunyuan-2.0-instruct-20251111 は 2026-05-31 にオフラインになりました。この ID は決して指定しないでください。
"custom-<your-name>"	CreateAIModel で登録したユーザー定義の GroupName です。custom- で始まる必要があります（例：custom-kimi、custom-openai-compat）。

❌ 次のいずれも記述しないでください — すべて誤りです

wx.cloud.extend.AI.createModel("deepseek")                   // wrong — vendor, not GroupName
wx.cloud.extend.AI.createModel("deepseek-v4-flash")          // wrong — model id goes in `model`
wx.cloud.extend.AI.createModel("hunyuan")                    // wrong — vendor family
wx.cloud.extend.AI.createModel("hunyuan-2.0-instruct-20251111")  // wrong — model name
wx.cloud.extend.AI.createModel("glm") / "kimi" / "minimax"   // wrong — vendor names
wx.cloud.extend.AI.createModel("custom")                     // wrong — placeholder
wx.cloud.extend.AI.createModel(modelName)                    // wrong — do not reuse the model-id variable

✅ 正しいパターン — provider と model は別々のフィールドです

// Growth Plan branch (enable hy3 in the console first)
const model = wx.cloud.extend.AI.createModel("cloudbase"); // ← provider / GroupName
await model.streamText({
  data: { model: "hy3", messages: [...] }  // ← concrete model id
});

// Token Credits branch
const model = wx.cloud.extend.AI.createModel("cloudbase");
await model.streamText({
  data: { model: "deepseek-v4-flash", messages: [...] }
});

判断手順（ユーザーが特定のモデルを指定した場合）

1. ユーザーが「DeepSeek v3.2 を使う」／「hunyuan thinking を使う」／「Kimi k2.6 を使う」／…と言います。
2. まず、以下の利用可否判断ツリーを実行してください。ほとんどの場合、成长计划の環境（cloudbase + hy3）を含め、provider は "cloudbase" です。"hunyuan-v3" は、それをすでに使用している既存コードにのみ登場します。"hunyuan-exp" は、DescribeAIModels がその古いグループをまだ返す場合に限ります。
3. モデル ID を data 内の**model フィールド**に指定します：{ model: "deepseek-v3.2" }、{ model: "hy3" }、{ model: "kimi-k2.6" }、…
4. モデル ID を使用する前に、DescribeAIModels({ GroupName: "cloudbase" }).Models[] に含まれていることを確認してください。含まれていない場合は、UpdateAIModel で有効にしてください。

wx.cloud.extend.AI.createModel( を入力しようとしていて、かっこの中身がベンダー名またはモデル ID なら、そこで止めてください。それはほぼ確実に、上記4つの有効な値のいずれかです。

---

必須の2段階事前確認

wx.cloud.extend.AI.createModel(...) にいきなり進んではいけません。ビジネスコードを書く前に、定められた順序で課金の利用可否とグループの準備状況を確認してください：① 利用可否 → ② グループの準備状況。順序を入れ替えないでください。

事前確認 ① · 課金の利用可否（2つの並行する課金経路）

ミニプログラム側には、小程序成长计划（最初に確認）と Token Credits 资源包（汎用フォールバック）の 2 つの課金経路があります。どちらも cloudbase メイン管理グループを通じて精算されます。成長計画ではモデルは hy3 で、プランのクォータが優先して消費されます。hunyuan-v3 は、プランのクォータのみを消費する旧プランのグループで、廃止予定です。

1. MCP ツール queryEnv action=info で envId を取得します。

2. ユーザーの意図に基づいて分岐を選びます。

ユーザーの意図	最初に確認する利用資格	利用資格がある場合の createModel プロバイダー	モデルの選択	利用資格がない場合の案内
モデルの指定なし／デフォルトの呼び出し	まず 小程序成长计划 への登録を確認します。未登録の場合は Token Credits リソースパックにフォールバックします	どちらの場合も "cloudbase"	登録済み：hy3（成長計画のテキストモデル。まず "cloudbase" グループで有効にします）。未登録：ユーザーとテキストモデルを選び、DescribeAIModels → DescribeManagedAIModelList → UpdateAIModel を使って "cloudbase" グループで確認・有効化します	プラン未登録 → https://docs.cloudbase.net/ai/ai-inspire-plan を案内します。リソースパックがない場合 → 購入リンクを案内します
ユーザーが hunyuan-* モデルをリクエスト	小程序成长计划 への登録	"cloudbase"（プランのクォータには hy3 を使用）	DescribeAIModels({ GroupName: "cloudbase" }).Models[] で指定された Model を確認し、存在しない場合は UpdateAIModel で有効化します	登録済みでモデルがない場合 → 有効化します。未登録の場合 → プランページを案内するか、"cloudbase" とリソースパックを使用します
ユーザーが deepseek-* / glm-* / kimi-* / minimax-* / その他の Hunyuan 以外の管理対象モデルをリクエスト	Token Credits 资源包 の有効化	"cloudbase"	モデルがすでに有効だと決めつけないでください。DescribeAIModels → モデルがない場合は DescribeManagedAIModelList で正式な Model 文字列を確認 → Status: 1 を指定した UpdateAIModel（Models[] 全体の置換）	リソースパックが有効化されていない場合 → 購入リンクを案内します
ユーザーがサードパーティ製／セルフホスト（管理対象外）モデルをリクエスト	課金資格の確認を省略し、「カスタムオンボーディング」に進みます	カスタムの GroupName（custom- で始まる必要があります）	CreateAIModel.Models[] で登録します	コンソールと CreateAIModel の両方の方法を案内します

3. 小程序成长计划への登録を確認します。

callCloudApi({
  service: "tcb",
  action: "DescribeActivityInfo",
  params: {
    ActivityNames: ["ai_miniprogram_inspire_plan"], // PascalCase preferred; switch to camelCase if InvalidParameter is returned
  },
})

登録済みの判定基準： レスポンスの attendRecords に、activityName === "ai_miniprogram_inspire_plan" かつ envId が現在の環境と一致するエントリーが 1 つ以上含まれていることです。登録済みの場合は、createModel("cloudbase") + model: "hy3" を使用します（先にグループで hy3 を有効にしてください）。呼び出しではプランの無料クォータが消費されます。createModel("hunyuan-v3") + hy3 を使う旧コードも引き続き動作しますが、そのグループは廃止予定です。cloudbase に移行してください。

⚠️ 付与された Token は、利用元によって適用範囲が異なります。 適用対象は、ミニプログラムのクライアント呼び出しと管理者 ID による呼び出し（コンソールのプレイグラウンド、クラウド関数内での呼び出し）のみです。それ以外の利用元からの呼び出しでは消費されず、代わりに環境のリソースポイントプールで精算されます。そのため、「Token パックが適用されず、リソースポイントが課金された」とユーザーに見えることがあります。そのような報告を受けたら、コードやモデル設定に手を加える前に呼び出し元を確認してください。以下の Token Credits パックの経路にも同じルールが適用されます。

登録されていない場合： 暗黙にフォールバックしてはいけません。「現在の環境は小程序成长计划に登録されていません」とユーザーに伝え、登録ページ https://docs.cloudbase.net/ai/ai-inspire-plan を案内したうえで、登録して再試行するか、Hunyuan 以外のモデルで Token Credits リソースパックの経路に切り替えるかを確認してください。

4. Token Credits リソースパックを確認します（経路が "cloudbase" メイン管理グループに進む場合）。

callCloudApi({
  service: "tcb",
  action: "DescribeEnvPostpayPackage",
  params: {
    EnvId: "<current envId>",
  },
})

有効の判定基準： envPostpayPackageInfoList に、postpayPackageId が pkg_tcb_tokencredits_ で始まり、status ∉ [3, 4]（期限切れでも無効化済みでもない）で、versionSwitchStatus がブロック状態ではないエントリーが含まれていることです。

有効でない場合： 購入リンクを案内します（{envId} は実際の ID に置き換えてください。プレースホルダーのままにしてはいけません）。

https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token

事前確認 ② · グループの準備状況（すべてのミニプログラム AI 呼び出しで必須）

利用資格を満たしていても、対象モデルを呼び出せるとは限りません。"cloudbase" メイン管理グループでは、デフォルトで有効なモデルはありません。まず DescribeAIModels を呼び出して有効なモデルを確認し、モデルが見つからない場合は DescribeManagedAIModelList で正式なサポートモデルカタログを確認してから、Status: 1 を指定して UpdateAIModel を呼び出し、有効にする必要があります。成長プランに登録していても、この確認は省略できません。hy3 が cloudbase グループに存在し、有効になっている必要があります。旧式の "hunyuan-v3" で公開されているのは hy3 のみで、廃止予定です。デフォルトではなく、読み取り専用の互換性用として扱ってください。

1. 環境で現在設定されているグループとスイッチを照会します（tcb Action DescribeAIModels、Version 2018-06-08）。

callCloudApi({
  service: "tcb",
  action: "DescribeAIModels",
  params: { EnvId: "<envId>" },
})

AIModelGroups: AIModelGroup[] が返されます。各 AIModelGroup には、GroupName（例：cloudbase / hunyuan-exp / カスタムグループ）、Type（builtin / custom）、Models: [{ Model, EnableMCP, Tags }]、Status（1=オン / 2=オフ）が含まれます。グループの準備が整っている状態とは、GroupName が存在し、Status === 1 で、対象の Model が Models[] に存在するという3つの条件をすべて満たすことです。

2. 対象モデルが DescribeAIModels の応答に含まれていない場合は、DescribeManagedAIModelList でプラットフォームのカタログと料金を照会します。この API は、ModelSpec（コンテキスト長など）と ModelChargingInfo（Uniform / Tiered 料金）を含む ManagedAIModelGroup[] を返します。対象モデルを選び、UpdateAIModel で有効にします。

callCloudApi({
  service: "tcb",
  action: "UpdateAIModel",
  params: {
    EnvId: "<envId>",
    GroupName: "cloudbase",
    Status: 1, // 1=on, 2=off
    Models: [
      { Model: "deepseek-v4-flash", EnableMCP: false },
      { Model: "deepseek-v3.2", EnableMCP: false },   // append the new model to enable
    ],
    // ⚠️ `Models` is a FULL REPLACEMENT, not incremental; merge the old list + new entries before passing.
  },
})

3. 両方の手順が完了したら、その後に限り、ミニプログラムのコードで wx.cloud.extend.AI.createModel("<GroupName>") を記述し、そのグループの Models[] に存在する model 値を渡します。

順序は固定です。 利用資格がなければ、有効なモデルがあっても課金されません。グループの準備が整っていなければ、利用資格があっても ModelNotEnabled クラスのエラーが返されます。どちらもビジネスコードを書く前に完了させる必要があります。

API の大文字・小文字に関するヒント： tcb のパブリックサービス Actions では、公式には PascalCase（EnvId、GroupName、ActivityNames）を使用します。一部のドキュメントでは camelCase が使われています。最初の呼び出しで InvalidParameter が発生した場合は、大文字・小文字を切り替えて再試行し、動作した形式をプロジェクトのラッパーで固定してください。

---

利用可能なプロバイダーとモデル

wx.cloud.extend.AI.createModel(provider) の provider 引数には、DescribeAIModels が返す GroupName を指定します。使用できる値は以下の4種類のみです。選択する前に判断フローを実行してください。

A. ミニプログラム成長プラン（登録時のデフォルト）— provider は cloudbase、model は hy3

createModel の provider	デフォルトモデル	その他の利用可能なモデル	備考
"cloudbase"	hy3	環境で有効になっているその他のモデル。DescribeAIModels({ GroupName: "cloudbase" }).Models[] で実行時に照会してください。ハードコードしないでください	呼び出し元が許可されている場合、まずプランのクォータが使用されます。最初の呼び出し前に UpdateAIModel で hy3 を有効にしてください
"hunyuan-v3"	hy3	なし — このグループで公開されているのは hy3 のみです	旧式のプラングループで、廃止予定です。既存のコードは動作しますが、cloudbase + hy3 に移行してください
"hunyuan-exp"	—	環境で引き続き返されるモデル	旧式の組み込みモデルです。元のデフォルトである hunyuan-2.0-instruct-20251111 はオフラインです（2026-05-31）。対象にしないでください

B. メインのマネージドグループ（Token Credits パックのシナリオ、推奨デフォルト）

"cloudbase" の GroupName は Tencent Cloud TokenHub によって提供されており、複数のファーストパーティおよびサードパーティのベンダーをカバーする統合マネージドプールです。Hunyuan ファミリー（HY 2.0 Instruct、HY 2.0 Think、Hunyuan-role、Hy3 preview、…）、DeepSeek ファミリー（DeepSeek-V4-Pro、DeepSeek-V4-Flash、Deepseek-v3.2、Deepseek-v3.1、Deepseek-r1-0528、Deepseek-v3-0324、…）、Zhipu GLM（GLM-5、GLM-5-Turbo、GLM-5.1、GLM-5V-Turbo）、Kimi（K2.5、K2.6）、MiniMax（M2.5、M2.7）などが含まれます。モデルのラインナップは随時更新されるため、アプリケーションコードにリストをハードコードしないでください。必ず実行時に確認してください。

createModel provider	モデルの準備状況	モデルを有効にする方法	備考
"cloudbase"	デフォルトではモデルが有効になっていません。まず必ず DescribeAIModels({ GroupName: "cloudbase" }).Models[] を確認してください	1) DescribeManagedAIModelList で正式なカタログと料金を取得します（Model 文字列を推測しないでください）。2) Status: 1 と、対象モデルを含む完全置換の Models[] を指定して UpdateAIModel を呼び出します	統合マネージドグループ（Type=builtin）、Remark "腾讯云开发"、pkg_tcb_tokencredits_* リソースパックが必要です

⚠️ ミニプログラムでよくある間違い：createModel("deepseek") / createModel("hunyuan") / createModel("glm") / createModel("kimi") / createModel("minimax") / createModel("custom") と記述することです。すべて誤りです。これらはベンダー名またはモデル名であり、プロバイダー名または GroupName ではありません。プロバイダーには、DescribeAIModels が返す GroupName の値を指定する必要があります。新しいプロジェクトでは常に統合マネージドグループ "cloudbase" を使用し、model フィールドで具体的なベンダーモデルを選択してください。

C. マネージドカタログにないモデル → カスタム登録

サードパーティ／セルフホスト可能／OpenAI 互換のエンドポイントを使用するモデル（A/B に記載されていないもの）は、上記の課金経路を通りません。まず「カスタム登録」で Type=custom の GroupName を登録する必要があります。次のセクションを参照してください。

---

カスタム登録（マネージドカタログにない場合）

ユーザーがメインのマネージドグループ（cloudbase）のカタログにないモデル（例：エンタープライズがホストする OpenAI 互換エンドポイント、サードパーティのモデルサービス）を指定した場合は、以下の2つの方法のいずれかを選択してください。「サードパーティ／セルフホスト可能／OpenAI 互換エンドポイント」など、中立的な表現を使用してください。競合他社の具体的なブランド名は挙げないでください。

方法1 · コンソールで登録

CloudBase コンソールの AI モデルページをユーザーに案内してください。

https://tcb.cloud.tencent.com/dev?envId={envId}#/ai

{envId} を実際の環境 ID に置き換え、モデル名、エンドポイント、API キーなどをユーザーに入力してもらいます。

方法2 · callCloudApi + CreateAIModel で登録

tcb Action の CreateAIModel（Version 2018-06-08）は、現在の環境に Type=custom の AI モデルグループを作成します。

callCloudApi({
  service: "tcb",
  action: "CreateAIModel",
  params: {
    EnvId: "<current envId>",
    GroupName: "custom-openai-compat",  // ⚠️ MUST start with "custom-" (e.g. custom-kimi, custom-moonshot) to avoid colliding with built-in / vendor GroupNames; this becomes the value passed to createModel(provider)
    BaseUrl: "https://api.example.com/v1",
    Models: [
      { Model: "gpt-4o-mini", EnableMCP: false },
      { Model: "gpt-4o",       EnableMCP: false },
    ],
    Remark: "Internal OpenAI-compatible endpoint",
    Status: 1,                         // 1=on, 2=off
    Secret: {
      // Key / ApiKey: pick one; OpenAI-compatible endpoints usually use ApiKey
      ApiKey: "<vendor-api-key>",
    },
  },
})

登録後：

• DescribeAIModels を実行し、GroupName が Status=1 で存在し、対象の Model が Models[] に含まれていることを確認します。
• ミニプログラムで wx.cloud.extend.AI.createModel("custom-openai-compat") を呼び出し、登録したモデル名（例："gpt-4o-mini"）を model フィールドに渡します。
• 後からモデルを追加または変更するには、UpdateAIModel を使用します（Models は完全置換です。Status はオン／オフに 1/2 を使用します）。カスタムグループ全体を削除するには、DeleteAIModel を使用します（カスタムグループのみ。GroupNames.N で一括処理できます）。
• すべての呼び出しは、引き続き環境の課金経路を使用します。このようなカスタムモデルでも Token 決済が必要な場合は、事前に対象となるか確認してください。

---

前提条件

• WeChat ベースライブラリ 3.7.1+
• SDK の追加インストールは不要です

---

初期化

// app.js
App({
  onLaunch: function() {
    wx.cloud.init({ env: "<YOUR_ENV_ID>" });
  }
})

---

generateText() - 非ストリーミング

⚠️ JS/Node SDKとは異なります： 戻り値はモデルの生のレスポンスです。

前提条件：「必須の2段階事前確認」が完了しており、DescribeAIModels を使って対象モデルが有効になっていることを確認済み（または、モデルが見つからない場合は UpdateAIModel を使って有効化済み）である必要があります。以下の例では、現在の環境が小程序成长计划に登録されており、createModel("cloudbase") + hy3 を使用していることを前提としています。対象が別の管理対象モデルの場合は、プロバイダーをそのままにして、ユーザーが選択し、UpdateAIModel で有効化したばかりのモデルを model に設定してください。deepseek-v4-flash がすでに利用可能だと決めつけてはいけません。

const model = wx.cloud.extend.AI.createModel("cloudbase");

const res = await model.generateText({
  model: "hy3",  // plan-enrolled default
  messages: [{ role: "user", content: "hi" }],
});

// ⚠️ Return value is the RAW model response, NOT wrapped like JS/Node SDK
console.log(res.choices[0].message.content);  // access via choices array
console.log(res.usage);                        // token usage

---

streamText() - ストリーミング

⚠️ JS/Node SDKとは異なります： パラメーターは必ず data オブジェクトでラップする必要があります。コールバックがサポートされています。

前提条件：「必須の2段階事前確認」が完了しており、対象モデルが有効になっている必要があります。以下の例では成长计划の分岐（cloudbase + hy3）を使用しています。別の管理対象モデルを使う場合は、プロバイダーをそのままにして、ユーザーが選択し、UpdateAIModel で有効化したばかりのモデルを model に設定してください（デフォルトで有効になっているモデルはありません）。

const model = wx.cloud.extend.AI.createModel("cloudbase");

// ⚠️ Parameters MUST be wrapped in a `data` object
const res = await model.streamText({
  data: {                              // ⚠️ Required wrapper
    model: "hy3",  // plan-enrolled default
    messages: [{ role: "user", content: "hi" }]
  },
  onText: (text) => {                  // Optional: incremental text callback
    console.log("New text:", text);
  },
  onEvent: ({ data }) => {             // Optional: raw event callback
    console.log("Event:", data);
  },
  onFinish: (fullText) => {            // Optional: completion callback
    console.log("Done:", fullText);
  }
});

// Async iteration is also available
for await (let str of res.textStream) {
  console.log(str);
}

// Check for completion via eventStream
for await (let event of res.eventStream) {
  console.log(event);
  if (event.data === "[DONE]") {       // ⚠️ Check for [DONE] to stop
    break;
  }
}

---

エラー処理パターン

前提条件：「必須の2段階事前確認」が完了している必要があります。リソースパックの分岐では、DescribeAIModels / UpdateAIModel を使って確認または有効化したばかりの特定のテキストモデルと "cloudbase" を使用してください。デフォルトで有効になっているモデルはありません。

const model = wx.cloud.extend.AI.createModel("cloudbase");

try {
  const res = await model.generateText({
    model: "deepseek-v4-flash",
    messages: [{ role: "user", content: "Write a welcome message" }],
  });

  console.log(res.choices[0].message.content);
} catch (error) {
  console.error("Mini Program AI request failed", error);
}

---

API 比較：JS/Node SDK と WeChat Mini Program

機能	JS/Node SDK	WeChat Mini Program
名前空間	app.ai()	wx.cloud.extend.AI
generateText のパラメーター	直接オブジェクトを指定	直接オブジェクトを指定
generateText の戻り値	{ text, usage, messages }	生データ：{ choices, usage }
streamText のパラメーター	直接オブジェクトを指定	⚠️ data: {...} でラップ
streamText の戻り値	{ textStream, dataStream }	{ textStream, eventStream }
コールバック	サポートされていません	onText、onEvent、onFinish
画像生成	Node SDK のみ	利用できません

---

型定義

streamText() の入力

interface WxStreamTextInput {
  data: {                              // ⚠️ Required wrapper object
    model: string;
    messages: Array<{
      role: "user" | "system" | "assistant";
      content: string;
    }>;
  };
  onText?: (text: string) => void;     // incremental text callback
  onEvent?: (prop: { data: string }) => void;  // raw event callback
  onFinish?: (text: string) => void;   // completion callback
}

streamText() の戻り値

interface WxStreamTextResult {
  textStream: AsyncIterable<string>;   // incremental text stream
  eventStream: AsyncIterable<{         // raw event stream
    event?: unknown;
    id?: unknown;
    data: string;                      // "[DONE]" when complete
  }>;
}

generateText() の戻り値

// Raw model response (OpenAI-compatible format)
interface WxGenerateTextResponse {
  id: string;
  object: "chat.completion";
  created: number;
  model: string;
  choices: Array<{
    index: number;
    message: {
      role: "assistant";
      content: string;
    };
    finish_reason: string;
  }>;
  usage: {
    prompt_tokens: number;
    completion_tokens: number;
    total_tokens: number;
  };
}

---

ベストプラクティス

1. ビジネスコードを書く前に、2 段階の事前確認を実施してください。 順序は固定です。① 請求の適用条件を確認するために DescribeActivityInfo / DescribeEnvPostpayPackage を実行 → ② グループの準備状況を確認するために DescribeAIModels を実行（必要に応じて、カタログと料金を確認するために DescribeManagedAIModelList を実行し、続いて対象モデルを有効にするために UpdateAIModel を実行）。両方の確認に合格してから、wx.cloud.extend.AI.createModel(...) を記述してください。
2. createModel(provider) が受け付ける値は 4 種類だけです — "cloudbase"（メインのマネージドグループ。新規プロジェクトおよび成長計画のデフォルト）、"hunyuan-v3"（旧プラングループ。hy3 のみで、廃止予定）、"hunyuan-exp"（さらに古い組み込みグループ）、またはカスタムオンボーディングの GroupName（必ず custom- で始めてください。組み込み名やベンダー名との衝突を避けるため、例：custom-kimi、custom-openai-compat）。createModel("deepseek")（DescribeAIModels が deepseek という名前の旧組み込みグループを実際に返す場合を除く）、createModel("hunyuan")、createModel("kimi")、createModel("custom") は絶対に記述しないでください。これらはモデル名／ベンダー名またはプレースホルダーであり、GroupName ではありません。
3. model フィールドには DescribeAIModels の値を指定してください。 選択したグループの Models[].Model リストに実際に存在する値を渡してください。メインのマネージドグループでは、デフォルトで有効なのは deepseek-v4-flash だけです。他のモデルを使うには、先に UpdateAIModel を呼び出してください。
4. プランのクォータはグループ名ではなく、成長計画に紐付いています。 登録済みの環境では、cloudbase + hy3 を通じて無料クォータが適用されます。hunyuan-v3（hy3 のみ）も引き続き適用されますが、廃止予定です。未登録の場合は、ユーザーに https://docs.cloudbase.net/ai/ai-inspire-plan を案内するか、リソースパックに含まれるモデルを "cloudbase" と組み合わせて使用してください。
5. モデルを追加で有効にする前に、料金を確認してください。 DescribeManagedAIModelList は ModelChargingInfo（一律料金の Uniform／段階料金の Tiered）と ModelSpec.ContextLength を返します。UpdateAIModel を呼び出す前に確認してください。Models は完全置換です。渡す前に、既存のリストと新しいエントリーをマージしてください。
6. 基本ライブラリのバージョンを確認してください。 3.7.1 以降が必要です。それより古いバージョンでは wx.cloud.extend.AI は undefined になります。これをモデルの問題としてデバッグしないでください。
7. UI の更新にはコールバックを使用してください。 onText はチャットの吹き出しを段階的に更新するのに適しています。eventStream から手動で連結すると、区切り文字が欠落しがちです。
8. [DONE] を確認してください。 eventStream を反復処理する場合は、event.data === "[DONE]" のときだけ処理を停止してください。そうしないと、次のフレームを永遠に待ち続けます。
9. data ラッパーを忘れないでください。 streamText のパラメーターは、JS/Node SDK とは異なり、必ず data: { ... } でラップしてください。これを忘れると、パラメーターエラーになります。
10. 「適用対象外／グループ未準備」と「呼び出し失敗」を区別してください。 前者では、登録／購入／UpdateAIModel の手順にユーザーを案内する必要があります。後者は、プロンプト、パラメーター、またはネットワークのデバッグに関する問題です。エラーメッセージも次の対応もまったく異なります。
11. ミニプログラムにサードパーティ製モデルの API キーをハードコードしないでください。 マネージドカタログにないモデルには、CreateAIModel の Secret.ApiKey を使用して、キーを CloudBase 側に保存してください。ミニプログラムには GroupName だけを保持してください。
12. TypeScript：型エラーを抑制するために any を使用しないでください。 wx.cloud.extend.AI の型定義がない場合は、実際に使用する部分に限定した正確な interface を宣言するか、ローカルの .d.ts で型を拡張してください。 : any、as any、@ts-ignore、@ts-nocheck は絶対に使用しないでください。
13. 完了を報告する前に、自分で検証してください。 ミニプログラムをビルドし、WeChat DevTools シミュレーターで開き、実際の streamText／generateText のフローをエンドツーエンドで実行して、次の点を確認してください。（a）テキストチャンクが onText 経由で届くこと、（b）[DONE] でストリームが終了すること、（c）新たなコンソールエラーがないこと。実際に実行せず「動作するはずです」とするのは、証拠として認められません。