Cherry Studio
Cherry StudioでAGTCloudを設定して使用します。
Cherry Studio は、Windows、macOS、Linux をサポートする複数モデルに対応したデスクトップクライアントです。カスタム OpenAI Providerを追加すると、Cherry Studio は AGTCloud の Chat Completions互換エンドポイントを使用できます。
このチュートリアルでは、基本的なチャット接続のみを紹介します。ドキュメント、画像、ツール呼び出し、推論、知識ベース、エージェント、MCP、およびその他の高度な機能は、Cherry Studio のバージョンと、対象モデルの実際の対応範囲によって異なります。
事前準備
開始前に、次の項目を確認してください。
- サポートされている Windows、macOS、または Linux デバイスを準備します。
- AGTCloudに登録してログインします。
- API Keys ページに AGTCloud API Keyを作成します。
- モデルマーケットプレイスから、現在の API Key で利用でき、Chat Completions に対応するモデル ID をコピーします。
Cherry Studioをダウンロードしてインストールする
Cherry Studio 公式ダウンロード ページ からインストール パッケージを取得します。バージョンによっては、ダウンロードページやインストールパッケージ名が更新される場合があります。オペレーティング システムとプロセッサ アーキテクチャに従って現在のバージョンを選択してください。
- 一般的な Intel または AMD コンピュータの場合は、Windows x64 の通常のインストール バージョンを選択します。
- Windows ARM デバイスの場合は、ARM64 インストール パッケージを選択します。
- ダウンロードが完了したら、インストール プログラムを実行し、インターフェイスのプロンプトに従ってインストールを完了します。
デバイスのアーキテクチャがわからない場合は、設定 → システム → システム情報 の「システム タイプ」を確認してください。
インストールが完了したら、Cherry Studio を起動します。初回起動時に初期化、データディレクトリ、またはアップデートのプロンプトが表示された場合は、現在のバージョンのインターフェースに従って設定を完了してください。
AGTCloud Providerを追加する
モデル提供設定を開く
Cherry Studio を開き、Settings → Model Provider と開きます。中国語インターフェイスの名前は、「設定 → モデル サービス」として表示される場合があります。
カスタム Providerを追加する
Provider リストで Add または [追加] をクリックして、新しいカスタム Providerを作成します。 Provider 名前に AGTCloud を入力し、Provider タイプに OpenAI を選択します。
接続情報を入力します
| Cherry Studio フィールド | 内容を入力してください |
|---|---|
Provider Name | AGTCloud |
Provider Type | OpenAI |
Chat Endpoint / Protocol(存在する場合) | OpenAI Chat Completions |
API Key | your-api-key |
API Host | https://api.agtcloud.cn/v1/ |
Custom Headers | デフォルトでは空欄にする |
your-api-key を、API Keys ページで作成した AGTCloud API Key に置き換えます。現在のバージョンでチャット プロトコルを選択できる場合は、OpenAI Chat Completions を使用してください。
Providerを有効にする
設定を保存した後、Providerの右上隅にある有効化スイッチをオンにします。Providerが有効になっていない場合、追加されたモデルはチャットページのモデルリストに表示されません。
API ホストは / で終わる必要があります
https://api.agtcloud.cn/v1/ を入力してください。完全な /v1/chat/completions リクエスト アドレスを入力しないでください。入力しないと、パスを再度結合するときに Cherry Studio が重複したエンドポイントを生成する可能性があります。
モデルを取得して追加する
オープンモデル管理
AGTCloud Provider設定ページで Manage をクリックします。 Cherry Studio は、現在の API ホストと API Key に基づいて表示可能なモデルを取得しようとします。
モデルをリストに追加
返されたモデルリストで Chat Completions をサポートするモデルを見つけて、右側の + をクリックします。Providerのモデル リストに追加されたモデルのみが、チャット ページのモデル セレクターに表示されます。
読み込みに失敗した場合は手動で追加する
モデル リストが正常に読み込まれない場合は、まず API ホスト、API Key、およびProviderのアクティベーション ステータスを確認してください。 モデルマーケットプレイス からモデルIDをコピーし、現在のバージョンで提供されている Cherry Studio 手動追加エントリを使用して MODEL_ID を入力することもできます。
接続を確認してください
API Key 入力ボックスの近くにある「接続チェック」ボタンをクリックします。 Cherry Studio 通常、追加されたリストの最後のチャット モデルがチェックに使用されます。チェックが失敗した場合は、まず、現在のAPI Keyで呼び出せるチャット モデルがリストに少なくとも 1 つあることを確認してください。
モデル設定は実際の機能に依存します
すべてのモデルを一度に追加する必要はありません。モデルのコンテキスト長、ファイル入力、画像理解、ツール呼び出しおよび推論機能は、現在のモデルとプロトコルの実際の対応範囲に依存します。
最初のチャットを開始する
新しいトピックを作成する
Cherry Studio チャット ページに戻り、新しいトピックを作成します。
AGTCloud モデルを選択してください
モデル セレクターを開き、AGTCloud → MODEL_ID を選択します。 MODEL_ID はプレースホルダーであり、実際のインターフェイスには追加したばかりのモデルID が表示されます。
チェック結果
クライアントが応答を正常に受信できれば、API Host、API Key、モデルを使った基本的な接続を確認できます。この手順では通常の API 利用量が発生します。
よくある質問
| 現象 | 優先して確認する項目 | 対処方法 |
|---|---|---|
| AGTCloud モデルが表示されない | Provider の切り替えとモデルの追加状況 | Provider を有効にし、対象モデルが Provider のモデル一覧に追加されていることを確認します。 |
Manage は空のリストを返します | API ホスト、API Key、現在のアカウントで利用可能なモデル範囲 | API ホストと API Keyを再入力するか、モデルマーケットプレイスから MODEL_ID をコピーして手動で追加します |
| 接続確認に失敗する | 追加したモデル、対応プロトコル、API Key の権限 | 一覧の最後にあるチャットモデルを、現在の API Key で Chat Completions 経由で呼び出せるか確認してください。 |
401 を返す | API Keyの内容とAPI Keyの状態 | 有効なAPI Keyを再度コピーします。入力された内容に余分なスペースが含まれていないことを確認してください。 |
403 を返す | トークンの権限、モデルの権限、およびアカウントのステータス | コンソールで API Key のステータスと現在のアカウントの利用可能なモデル範囲を確認します。 |
404 を返す | API ホスト、重複パス、およびモデルID | https://api.agtcloud.cn/v1/ を使用し、エンドポイント全体を入力せず、モデルIDを再確認してください。 |
| リクエストパスが重複する | API Host にエンドポイント全体を入力していないか | / で終わる https://api.agtcloud.cn/v1/ に戻し、接続を再確認します |
| 高度な機能の呼び出しに失敗する | モデルの実際の対応範囲、対応プロトコル、クライアントのバージョン | まずファイル、ツール、ナレッジベース、推論などの高度な機能を無効にし、通常のテキストで検証してください。 |
| 返信が途切れたり遅くなったりする | ネットワーク プロキシ、コンテキストの長さ、モデルの状態 | 新しい短いトピックで再試行し、ローカル ネットワークと現在のモデルの実行ステータスを確認してください。 |
特定できない問題が発生した場合は、リクエスト時間、モデルID、HTTP ステータス、および機密情報を除いたエラー情報を記録し、エラーとトラブルシューティング を確認してください。完全なAPI Keyを送信しないでください。
セキュリティ上の推奨事項
- スクリーンショット、チャットのエクスポート、ログ、または共有設定に API Keyを含めないでください。
- 最初の検証中に、パスワード、顧客データ、プライベート ファイル、またはその他の機密コンテンツを送信しないでください。
- 複数のユーザーがデバイスを共有する場合は、使用後に Cherry Studio に保存された認証情報を削除してください。
- Cherry Studio 構成をエクスポートまたは共有する前に、API Key が含まれていないことを確認してください。