ai-model-nodejs

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

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

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

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

@cloudbase/node-sdk を使用して、Node.js バックエンド、クラウド関数、または CloudRun サービスから AI モデルを呼び出す場合に、このスキルを使用してください。

🧭 実行環境の適合性。 AI の呼び出しがサーバー上で行われるべき場合に適したスキルです。画像生成（対応している SDK はこれだけです）、長時間実行するエージェントジョブ、複数のツールにまたがるオーケストレーション、スケジュールされたタスク、シークレットをサーバー側に保持する必要があるフローなどが該当します。Web ページ／フロントエンドの AI チャット UI を構築する場合、この SDK をバックエンドプロキシ経由で使ってはいけません。ai-model-web に振り分け、ブラウザーからモデルを直接呼び出してください。WeChat ミニプログラムでは ai-model-wechat を使用してください。振り分けはまず実行環境によって決まり、具体的なモデル（deepseek-*、glm-*、hunyuan-*、kimi-*、…）は model フィールドにのみ影響します。

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

• バックエンドサービスに AI テキスト生成を統合する
• Hunyuan Image モデルで画像を生成する
• CloudBase クラウド関数または CloudRun から AI モデルを呼び出す
• サーバー側で AI 処理を行う（エージェントのオーケストレーション、バッチジョブ、スケジュールされたタスク）

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

• ブラウザー／Web アプリ → ai-model-web スキルを使用してください
• WeChat ミニプログラム → ai-model-wechat スキルを使用してください
• CloudBase SDK のない実行環境（Python、Go、PHP、curl など） → http-api-cloudbase スキルを使用してください（このスキルには、AI モデルエンドポイントを HTTP で直接呼び出すための ai_model OpenAPI 仕様が含まれています。この SDK を HTTP プロキシ経由で使ってはいけません）

---

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

createModel(...) の行を記述する前に、必ずお読みください。エージェントがこの引数を頻繁に誤って生成します。使用できる形式はちょうど3つです。それ以外はバグです。

✅ 使用できる ai.createModel(...) の引数	使用する場合
"cloudbase"	サーバー側プロジェクトのメインのマネージドグループ（TokenHub を利用するマルチベンダープール）です。ベンダー名と具体的なモデル名は、generateText／streamText の model フィールドに指定します。例：{ model: "deepseek-v4-flash" }。デフォルトで有効になっているモデルはありません。SDK を呼び出す前に必ず DescribeAIModels を確認し、対象モデルがなければ UpdateAIModel で有効にしてください。
"hunyuan-exp"	現在の環境で DescribeAIModels がこのレガシー組み込みグループを明示的に返す場合にのみ使用してください。
"custom-<your-name>"	CreateAIModel を通じて登録したユーザー定義の GroupName です。必ず custom- で始めてください（例：custom-kimi、custom-openai-compat）。

画像生成には別のエントリポイントを使用します：ai.createImageModel("hunyuan-image")。これを createModel(...) と混同しないでください。

❌ 誤った引数のパターン

上記の3つの使用可能な値以外はすべて誤りです。ベンダー名（"deepseek"、"glm"、"kimi"、"openai"、"moonshot"、…）、具体的なモデル ID（"deepseek-v4-flash"、"hunyuan-2.0-instruct-20251111"）、プレースホルダーだけの "custom"、モデル ID を保持する変数はいずれも、createModel(...) ではバグになります。

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

const model = ai.createModel("cloudbase");          // ← GroupName
await model.generateText({
  model: "deepseek-v4-flash",                       // ← concrete model id
  messages: [...]
});

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

1. ユーザーが「DeepSeek v3.2を使って」／「hunyuan instructを使って」／「Kimi k2.6を使って」／「GLM-5を使って」／…と言います。
2. createModel("cloudbase") は変更しません。
3. モデル ID を model フィールドに指定します：{ model: "deepseek-v3.2" }、{ model: "hunyuan-2.0-instruct-20251111" }、{ model: "kimi-k2.6" }、{ model: "glm-5" }、…
4. モデルがすでに有効になっていると決めつけてはいけません。 SDK を呼び出す前に、DescribeAIModels({ GroupName: "cloudbase" }).Models[] にモデルが存在することを確認してください。存在しない場合は、DescribeManagedAIModelList を呼び出し、プラットフォームがサポートする正確な Model 名を確認してから（大文字と小文字を区別します。スペルを推測しないでください）、Status: 1 を指定して UpdateAIModel で有効にしてください（Models は全体置換であることに注意してください）。

ai.createModel( と入力しようとしていて、かっこの中身がベンダー名、モデル名、または推測した値である場合は、止めてください。上記の3つの有効な値のいずれかである可能性がほとんどです。

---

必須の2段階事前確認（SDK コードを記述する前）

サーバー上で AI API を呼び出す前に、2段階の事前確認を実行してください：①利用資格、②グループの準備状況。テキスト生成と画像生成は同じ Token Credits リソースパックを使用するため、コードを出力する前に、どちらも事前確認を完了する必要があります。

ステップ 0：環境 ID を取得する

MCP ツール queryEnv を action=info で呼び出し、レスポンスから EnvId を読み取ります。

---

事前確認 ① — 利用資格（Token Credits リソースパック）

MCP ツールを呼び出します：

callCloudApi(service="tcb", action="DescribeEnvPostpayPackage", params={ EnvId })

合格条件（すべて必須）：

• envPostpayPackageInfoList に1つ以上のエントリが含まれている

• そのエントリの postpayPackageId が pkg_tcb_tokencredits_ で始まっている

• そのエントリの status が [3, 4] に含まれていない（通常、3／4は期限切れ／無効を意味します。実際のレスポンスを優先してください）

• ❌ 条件を満たさない → コードの記述を中止し、{envId} を実際の ID に置き換えて、次の内容をユーザーに提示してください：

  現在の環境には有効な Token Credits リソースパックがありません。AI API を呼び出す前に購入してください： https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token

  購入が完了したらお知らせください。リソースパックのステータスを再確認します。

• ✅ 条件を満たす → 事前確認 ② に進みます。

パラメーターの大文字と小文字の形式は、契約により PascalCase です。呼び出しが InvalidParameter を返す場合は、camelCase（envId）に切り替えて、実際のレスポンスを優先してください。

---

事前確認 ② — グループの準備状況（DescribeAIModels → 必要に応じて UpdateAIModel）

対象資格を満たしているだけでは不十分です。まだ createModel("cloudbase") を呼び出さないでください。 まず、対象の GroupName が環境内に存在し、Status=1 であること、また対象の Model がその Models[] に含まれていることを確認してください。

1. 現在の環境で設定されているグループを一覧表示します。

   callCloudApi(service="tcb", action="DescribeAIModels", params={ EnvId })
   

   GroupName、Type（builtin ／ custom）、Models: [{ Model, EnableMCP, Tags }]、Status（1 ／ 2）、BaseUrl、Secret、Remark を含む AIModelGroups: AIModelGroup[] が返されます。主な管理対象の GroupName は cloudbase です。

2. モデルがすでに有効になっていると決めつけないでください。 対象グループの AIModelGroups[?].Models[].Model を確認してください。使用予定のテキストモデル（例：deepseek-v4-flash、またはユーザーが指定したモデル）が cloudbase グループの Models[] にない場合は、手順 4 に進んで有効にしてください。まだ createModel("cloudbase") を呼び出さないでください。画像生成では createImageModel("hunyuan-image") と model: "hunyuan-image" を使用します。呼び出す前に、同様に有効になっていることを確認してください。

3. ユーザーが管理カタログ内のモデル（例：deepseek-v3.2、hunyuan-2.0-instruct-20251111）を指定した場合： その Model がすでに cloudbase グループの Models[] にあるか確認してください。ない場合は、手順 4 に進んでください。正確なモデル ID を推測しないでください。 まず DescribeManagedAIModelList で正式な表記を確認してください。

4. 管理対象モデルを有効化／追加します（必ず最初に、信頼できるカタログと料金を確認してください）。

   callCloudApi(service="tcb", action="DescribeManagedAIModelList", params={ EnvId })
   

   GroupName、Remark、Models: [{ Model, EnableMCP, ModelSpec, ModelChargingInfo }] を含む ManagedAIModelGroup[] が返されます。対応モデル名と料金の唯一の情報源です。記憶を頼りに推測しないでください。UpdateAIModel の呼び出しには、ここに記載された正確な Model 文字列を使用してください。 ModelChargingInfo には入力／出力の料金と課金単位が含まれます。有効化する前に、料金をユーザーに提示してください。

   次に有効化します（注意：Models は全置換です。有効化済みのモデルも、新しいモデルと合わせて必ず再送してください）。

   callCloudApi(service="tcb", action="UpdateAIModel", params={
     EnvId,
     GroupName: "cloudbase",
     Models: [
       // resend every model that DescribeAIModels already showed as enabled
       { Model: "<already-enabled model>" },
       // append the newly-requested one, using the exact spelling from DescribeManagedAIModelList
       { Model: "<target model>" }
     ],
     Status: 1
   })
   

5. 要求されたモデルが管理カタログにない場合（DescribeManagedAIModelList で見つからない場合）→ 次のセクション「管理カタログ外のモデルのカスタム導入」に進んでください。

すべての Action で service=tcb、Version=2018-06-08 を使用します。パラメーターは PascalCase です。InvalidParameter の場合に限り、camelCase に切り替えてください。

---

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

ai.createModel(<GroupName>) で指定できる値は、正当な値として認められる 3 種類に限られます。画像生成専用のエントリーポイントは ai.createImageModel("hunyuan-image") です。

1. "cloudbase" — 主な管理対象グループ（推奨）

• GroupName: "cloudbase"、Type: "builtin"、Remark: "腾讯云开发"（Tencent CloudBase）
• Tencent Cloud TokenHub を基盤とする、複数ベンダーを対象とした統合管理プールです。Hunyuan（HY 2.0 Instruct、HY 2.0 Think、Hunyuan-role、Hy3 プレビューなど）、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）などをカバーしています。モデルのラインアップは更新されるため、特定の SKU をハードコードしないでください。 実行時に検出してください。
• デフォルトで有効になっているモデルはありません。 必ず最初に DescribeAIModels を呼び出し、環境で実際に有効になっているモデルを確認してください。対象のモデルがない場合は、DescribeManagedAIModelList で信頼できるカタログと料金を確認し、SDK を呼び出す前に UpdateAIModel（Status: 1、Models は全置換）で有効にしてください。
• 信頼できるカタログと料金：DescribeManagedAIModelList
• 環境で有効になっているモデル：DescribeAIModels

2. "hunyuan-exp" — 互換性のために維持されているレガシー組み込みグループ

• デフォルトモデル：hunyuan-2.0-instruct-20251111。追加の Hunyuan SKU は、実行時に DescribeAIModels({ GroupName: "hunyuan-exp" }).Models[] を使って検出する必要があります。他の ID をハードコードしないでください。
• DescribeAIModels が実際にこのグループを Status=1 で返した場合に限り、直接使用してください。新しいプロジェクトでは cloudbase を優先してください。

3. ユーザー定義の GroupName

• CreateAIModel を使ってオンボーディングします（次のセクションを参照）。カスタム GroupName は必ず custom- で始めてください（例：custom-kimi、custom-moonshot、custom-openai-compat）。この命名規則により、プラットフォームが将来追加する可能性のある組み込み／ベンダーの GroupName（cloudbase、hunyuan-exp、deepseek、glm、kimi、minimax など）との衝突を防げます。
• 例：createModel("custom-kimi")、createModel("custom-openai-compat")

画像生成（独立した API）

• ai.createImageModel("hunyuan-image") + model: "hunyuan-image"。Node SDK でのみサポートされています。

DescribeAIModels がその正確な GroupName を明示的に返していない限り、createModel("deepseek") や createModel("custom") のような推測でコードを書かないでください。

---

カスタムオンボーディング（管理対象カタログ外のモデル）

ユーザーが管理対象外のテキストモデル（セルフホスト、自社内、サードパーティの OpenAI 互換エンドポイントなど）を希望する場合、利用を妨げないでください。コンソールでの手順、CreateAIModel の完全なペイロード、その後の管理手順に沿ってオンボーディングを案内してください：custom-onboarding.md。カスタム GroupName は必ず custom- で始めてください。カスタムモデルの料金はサードパーティプロバイダーが請求し、Token Credits リソースパックからは差し引かれません。

---

インストール

npm install @cloudbase/node-sdk

⚠️ AI 機能を使用するには、バージョン 3.16.0 以上が必要です。 npm list @cloudbase/node-sdk で確認してください。

---

初期化

CloudBase クラウド関数内

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({ env: '<YOUR_ENV_ID>' });

exports.main = async (event, context) => {
  const ai = app.ai();
  // Use AI features
};

AI モデル向けのクラウド関数の設定

⚠️ 重要： AI モデルを使用するクラウド関数（特に generateImage() と大規模なテキスト生成）を作成する際は、タイムアウトを長めに設定してください。これらの処理には時間がかかる場合があります。

MCP ツール manageFunctions(action="createFunction") を使用する場合：

レガシー互換性：古いプロンプトに createFunction と記載されている場合も、同じペイロード形式を維持し、manageFunctions(action="createFunction") を通じて実行してください。

func オブジェクト内に timeout を設定します。

• パラメーター：func.timeout（数値）
• 単位：秒
• 範囲：1～900
• デフォルト：20 秒（通常、AI 処理には短すぎます）

推奨タイムアウト：

• テキスト生成（generateText）：60～120 秒
• ストリーミング（streamText）：60～120 秒
• 画像生成（generateImage）：300～900 秒（推奨：900 秒）
• 複合処理：900 秒（許可される最大値）

通常の Node.js サーバー内

const tcb = require('@cloudbase/node-sdk');
const app = tcb.init({
  env: '<YOUR_ENV_ID>',
  secretId: '<YOUR_SECRET_ID>',
  secretKey: '<YOUR_SECRET_KEY>'
});

const ai = app.ai();

---

SDK API リファレンス（必要に応じて参照）

generateText／streamText／generateImage のコード例、エラー処理パターン、画像生成パラメーター、TypeScript の型定義全般については、api-reference.md を参照してください。このファイルは、この SKILL.md とともに、@cloudbase/node-sdk の AI 機能に関する正式なリファレンスです。コードを書く前に、ここでメソッドのシグネチャを確認してください。メソッドやフィールドがここに記載されていない場合は、作業を中断して確認するか、MCP ツールを通じて最新の仕様を確認してください。推測は禁物です。

---

ベストプラクティス

1. ビジネスコードを書く前に、2 段階の事前チェックを実行してください — ①利用資格：queryEnv → callCloudApi(tcb, DescribeEnvPostpayPackage) を実行し、Token クレジットのリソースパックがあることを確認します（テキストと画像は同じパックを共有します）。②グループの準備状況：cloudbase グループとその Models[] について DescribeAIModels を実行し、正式な対応モデルカタログについて DescribeManagedAIModelList を実行します。対象モデルがない場合は、Models[] を全置換し、Status: 1 を設定して UpdateAIModel を実行します。パックがない場合は、SDK コードを出力してユーザーに実行時エラーをデバッグさせるのではなく、購入リンク https://buy.cloud.tencent.com/lowcode?buyType=resPack&envId={envId}&resourceType=token を返してください。
2. すでに有効になっているモデルがあると決めつけないでください — deepseek-v4-flash も、hunyuan-image も、ほかのモデルも例外ではありません。必ず最初に DescribeAIModels で確認してください。対象モデルがない場合は、DescribeManagedAIModelList で正確な Model 文字列を調べて（綴りを推測してはいけません）、その後 UpdateAIModel で有効にしてください。
3. createModel が受け取る値は、正確に次の 3 種類です — "cloudbase"（メインのマネージドグループ）、"hunyuan-exp"（レガシー組み込みモデル）、または CreateAIModel で登録したユーザー定義の GroupName（必ず custom- で始めてください。例：custom-kimi、custom-openai-compat）。createModel("deepseek") / createModel("kimi") / createModel("custom") のように推測して指定してはいけません — 最初の 2 つはベンダー名／モデル名で、最後のものはプレースホルダーです。createImageModel("hunyuan-image") は別の画像 API です — そのまま使用してください。
4. SDK のメソッド名やパラメーターを作り出してはいけません。 このスキル（SKILL.md + references/api-reference.md）は、@cloudbase/node-sdk の AI 機能に関する正式なリファレンスです。コードを書く前に、そこでメソッドのシグネチャを確認してください。メソッドやフィールドが記載されていない場合は、作業を止めて確認するか、MCP ツールで実際の仕様を確認してください。推測は禁止です。
5. 新しいマネージドモデルを有効にする前に、料金を提示してください — DescribeManagedAIModelList は、ModelSpec（コンテキスト長、最大入力／出力トークン数）と ModelChargingInfo（入力／出力／キャッシュの料金、課金単位）を返します。UpdateAIModel を呼び出す前に、ユーザーに料金を提示してください。
6. 画像生成では、タイムアウトとクォータを個別に計画してください — generateImage はテキストより 1 回あたりのコストが高く、実行にも時間がかかります。クラウド関数では timeout を 900s に設定してください。HTTP 関数のゲートウェイは 60s が上限なので、非同期タスク + ポーリングのパターンを使用してください。1 回の失敗で Token パックを使い切らないよう、ユーザーごとの同時実行数と呼び出し頻度を制限してください。
7. 長いやり取りでは、ストリーミングを優先してください — HTTP 関数またはクラウド関数の SSE シナリオでは、streamText + for await (const chunk of result.textStream) を使用して、チャンクをクライアントに逐次送信してください。catch でストリームの中断を処理し、基盤となるレスポンスを閉じてください。
8. サーバーでは @cloudbase/node-sdk を 3.16.0 以上に固定してください — 画像生成はこのバージョン以降でのみ使用できます。クラウド関数／Cloud Run ランタイムで実際に読み込まれるバージョンを確認するため、npm ls @cloudbase/node-sdk を実行してください。ローカル環境と本番環境のバージョンは異なる場合があります。
9. モデル名は、コード中に散在させず設定にまとめてください。 選択したテキスト／画像モデルは 1 つの定数で管理し、DescribeAIModels／DescribeManagedAIModelList から取得してください。マネージドカタログは変更されるため、信頼できる情報源を 1 つにまとめておけば、アップグレードが容易になります。マネージドカタログにないモデルについては、カスタムオンボーディングのセクションに従ってください — サードパーティー API キーをビジネスコードにハードコードせず、CloudBase 経由で CreateAIModel.Secret.ApiKey に保持してください。
10. 「事前チェックの失敗」と「モデル呼び出しの失敗」を区別してください — 前者はリソースパックが有効でないか、UpdateAIModel で対象モデルが有効になっていないことを意味します（購入／有効化をユーザーに案内してください）。後者はパラメーターの問題か、上流でのエラーです。両方を汎用的なトースト 1 つで処理してはいけません。
11. 本番環境では、プロンプト全文や生成テキストをログに出力しないでください — usage.total_tokens と短い冒頭部分だけを記録してください。プロンプトから機密情報が漏れる可能性があり、トークン数からコストに関する情報が漏れる可能性があります。
12. TypeScript では、SDK の型エラーを抑制するために any を使わないでください。 Node SDK には独自の型が含まれています。unknown と型ガードで型を絞るか、使用するデータ構造に合わせた正確な interface を記述するか、ローカルの .d.ts で型を拡張してください。: any、as any、@ts-ignore、@ts-nocheck は使用しないでください。web-development スキルの Engineering constitution を参照してください — バックエンドの TypeScript にも適用されます。
13. 完了を宣言する前に、自分で検証してください。 tsc --noEmit とプロジェクトのビルドを実行し、関数を実際に呼び出して（ローカル呼び出し／manageFunctions(action="invokeFunction")／HTTP への直接リクエスト）、usage.total_tokens > 0 であることと、返されたテキストがエラーエンベロープではないことを確認してください。実際の往復を確認せずに「動くはずです」と言うだけでは、十分な根拠になりません。

リファレンス一覧

スキルのリント到達性に必要な、パッケージ化されたすべてのリファレンスファイル：

• API リファレンス — generateText / streamText / generateImage の例、エラー処理パターン、画像パラメーター、TypeScript 型定義
• カスタムオンボーディング — 管理対象カタログ外のオンボーディングモデル（コンソールのフロー + CreateAIModel）