よくある質問

タスクプラグインの権限、インポート、互換性、ルーティング、チャネル、課金、成果物の問題をトラブルシューティングします。

タスクプラグインページが表示されない、または403エラーが返されるのはなぜですか？

プラグイン管理ページ /task-plugins および /api/plugin/task 管理APIはRoot権限を要求します。通常の管理者ロールやモデルAPIキーだけでは不十分です。また、デプロイバージョンにタスクプラグイン機能が含まれていることを確認する必要があります。

管理者がチャネルでプラグインを選択する場合、独立したプラグインバインド権限を使用します。詳細については、チャネル設定を参照してください。

ドキュメントサイトのマーケットプレイスの読み込みに失敗した場合はどうすればよいですか？

「再読み込み」をクリックしてください。マーケットプレイスデータはドキュメントドメインに応じて対応する公式サイトから読み込まれます：.pro は www.newapi.pro を使用し、.ai は www.newapi.ai を使用します。ローカルプレビューはデフォルトで .ai を使用します。日本語自体はデータソースを切り替えません。

サイトが一時的にデータを読み取れない場合でも、インストールおよび開発チュートリアルは利用可能です。ドキュメントサイトをデプロイする管理者は、サーバーサイドから対応する公式サイトへのネットワーク、および公開されている /api/v1/plugins エンドポイントが到達可能であることを確認する必要があります。

URLインポートが失敗するのはなぜですか？

貼り付けたのが完全な plugin.js のアドレスであり、HTMLマーケットプレイスページやGitHubの blob ページではないことを確認してください。ブラウザがそのアドレスを読み取れるか、オリジンサーバーがクロスオリジンリクエストを許可しているか、およびソースコードが1 MiBを超えていないかを確認してください。

ドキュメントサイトのマーケットプレイスのコピーボタンを使用すると、公式サイトのホスティングアドレスを取得できます。クリップボードの権限が不足している場合、コピーに失敗すると手動で選択可能なアドレスが表示されます。

SHA-256が一致しない場合はどうすればよいですか？

検証をスキップしてインストールを続行しないでください。マーケットプレイスディレクトリを更新してソースコードを再読み込みし、オリジンサーバーが公開中か、またはミラーが不一致のバージョンをキャッシュしているかを確認してください。マーケットプレイスの公開者は、ソースコードが生成されたインデックスとともに公開され、公開済みバージョンが上書きされていないことを確認する必要があります。

手動アップロードおよび通常のURLインポートは、マーケットプレイスインデックスハッシュ検証が完了したとは見なされません。完全なプロセスについては、インストールと管理を参照してください。

`apiVersion: 1` なのに互換性がないのはなぜですか？

API v1では、usageProfiles、unitLabel、requiredCapabilities、またはSSE機能が追加される可能性があります。古いホストは、バージョン番号が同じ1であっても、サポートされていないフィールドと機能を拒否します。

まずリリースログを読み、これらの機能をサポートするホストにアップグレードするか、現在のホストと互換性のあるプラグインバージョンを選択してください。検証を回避するために機能宣言を単純に削除しないでください。

インストール時にチャネルタイプまたはルーティングの競合が報告された場合はどうすればよいですか？

エラーで示された別のプラグインを確認し、双方の channelTypes とネイティブルーティングを照合してください。古いチャネルタイプの所有権は一意である必要があり、ネイティブルーティングも競合するHTTPメソッドとパス形状を登録してはなりません。

同じホストプロトコル下でのモデル共有は許可されており、モデル名が同じという理由だけでプラグインを削除する必要はありません。まず実際の競合タイプを確認し、その後バージョンまたはプラグイン設定を調整してください。

インストールが成功しても呼び出せないのはなぜですか？

順に確認してください：

タスクプラグインの全体スイッチがオンになっているか、ターゲットバージョンがアクティブ化されているか。
対応するチャネルが有効になっているか、Task Pluginチャネルが正しいキーにバインドされているか。
モデル名、チャネルモデルマッピング、グループ、APIキーの権限が一致しているか。
リクエストに使用されるエントリポイントがプラグインによって宣言されているか、Responsesリクエストパターンがサポートされているか。
Base URL、認証情報、およびこのモデルの課金設定が正しいか。

プラグインをインストールしても、利用可能なチャネルが自動的に作成されたり、管理者に代わって価格が決定されたりすることはありません。

`model_price_error` または使用量が一致しない場合はどうすればよいですか？

現在実行中のプラグインが現在のモデルに対して宣言しているスキーマを確認してください。共有モデルの異なるプロバイダーは異なるフィールドを報告する可能性があり、モデルのデフォルト式に互換性がない場合は、そのプラグインのために独立した式を保存してください。

アップグレードによって使用量フィールドまたはプロファイルが変更された場合、古い式は自動的に移行されません。移行ガイドに従って関連価格を変更してください。詳細については、使用量と課金を参照してください。

タスクの処理に時間がかかりすぎる、またはポーリングが失敗した場合はどうすればよいですか？

タスクログ、アップストリーム認証、および応答ステータスを確認してください。404/410は失敗返金になります。401/403、429、5xxまたはネットワーク障害はポーリング失敗として累積されます。不明なタスクステータスも失敗と見なされ、プラグインによって強制的にIN_PROGRESSに変換されるべきではありません。

ホストはデフォルトで、連続20回のポーリング失敗後にタスクを失敗としてマークし、TASK_TIMEOUT_MINUTES によって制御されるタスクタイムアウトメカニズムにも制約されます。まずアップストリームエラーまたは解析の問題を特定し、失敗回数を増やすだけではいけません。

アップグレード後にノード間で動作が異なるのはなぜですか？

Rootは各ノードの GET /api/plugin/task/runtime/status を読み取ることができ、現在のgeneration、データベースのオーバーライドリビジョン、最新の再構築結果、およびプラグインレベルのエラーを確認できます。

generationはノードのローカル番号であり、異なるノード間ではデータベースのリビジョンを比較する必要があります。データベースが一時的に読み取り不可の場合でも、APIはノードの既存の状態を返し、database_error が付与されます。新しいバージョンも進行中のタスクのデータを引き続き解析する必要があります。これは、バックグラウンドポーリングが新しくアクティブ化されたバージョンを使用する可能性があるためです。

プラグインのデバッグログを確認するにはどうすればよいですか？

DEBUG=true でNew APIを起動し、task_plugin でログをフィルタリングすると、登録、ルーティング、チャネル選択、送信、ポーリング、プロトコル監視イベントを確認できます。リクエスト関連イベントにはリクエストIDが付与され、バックグラウンドイベントはSYSTEMとしてマークされる場合があります。

プラグインのconsole.logもDEBUGモードで転送される可能性があります。秘密鍵、認証ヘッダー、リクエストボディ、完全なアップストリームペイロード、またはプライベートURLを出力しないでください。個々のフックの検証は、開発ガイドのサンドボックスとフィクスチャを使用できます。

成果物リンクにアクセスできないのはなぜですか？

まずタスクが成功し、プラグインが成果物フックを実装していることを確認し、その後実際に返された成果物キーまたはcontent_urlを使用してください。TaskPublicAddress を確認してください。設定されていない場合、ホストはServerAddressにフォールバックします。

マルチノードデプロイメントでは、有効なCRYPTO_SECRETを共有する必要があります。発行された成果物アクセスリンクには有効期限がありませんが、キーをローテーションすると古いリンクは無効になります。リクエスト時には、タスクと対応するプラグインをロードできる必要があります。アクセス資格情報を含む成果物リンクを公開しないでください。

オーバーライドバージョンを無効にした後もプラグインが残っているのはなぜですか？

同じキーで組み込みプラグインが存在する場合、カスタムオーバーライドバージョンを無効化または削除すると、組み込み実装が復元されます。組み込みプラグインは個別に削除または無効化できません。全体スイッチをオフにすると、他のプラグインを含むプラグインシステム全体が停止します。

目次