このガイドでは、Discourse AI プラグイン内の LLM、埋め込みモデル、カスタム AI ツール全体で、AI 認証情報（共有シークレット）の作成、管理、使用方法について説明します。
必要なユーザーレベル：管理者
概要
AI 認証情報は、Discourse AI 設定全体で API キーなどの認証シークレットを一元管理し、安全に管理するための方法です。生 API キーを個々の LLM モデル、埋め込み定義、カスタムツールに貼り付ける代わりに、認証情報を一度作成し、必要な場所で参照します。
キーをローテーションする場合（例：OpenAI API キー）、1 か所で更新するだけで、その認証情報を使用しているすべての LLM、埋め込み、ツールが自動的に変更を反映します。
このドキュメントでは、以下の内容を扱います。
- 認証情報の作成と管理
- LLM および埋め込みモデルへの認証情報のリンク
- カスタム AI ツールでの認証情報の使用
- 削除保護と認証情報のライフサイクル
- 認証情報のプログラムによる管理を行うための API
認証情報とは？
認証情報とは、Discourse AI に一元保存された、名前付きで再利用可能なシークレットです。主に以下の 2 つのフィールドを持ちます。
| フィールド | 説明 |
|---|---|
| 名前 | 一意で人間が読みやすいラベル（例：「OpenAI API キー」）。最大 100 文字。 |
| 値 | 実際のシークレット（API キー、トークンなど）。最大 10,000 文字。 |
認証情報は、以下の 3 種類のエンティティから参照できます。
- LLM モデル — 主要な API キーとして
- 埋め込み定義 — 主要な API キーとして
- カスタム AI ツール — JavaScript からアクセスされる名前付きシークレットバインディングとして
さらに、AWS Bedrock の access_key_id などの「シークレット」タイプの特定の LLM プロバイダーパラメータも、認証情報を参照します。
認証情報の作成と管理
認証情報ページへのアクセス
管理 → プラグイン → Discourse AI → 認証情報 に移動するか、/admin/plugins/discourse-ai/ai-secrets に直接アクセスします。
[screenshot placeholder: credentials list page showing name, used-by, and edit button columns]
新しい認証情報の作成
- 認証情報ページで、**「新しい認証情報」**をクリックします。
- 認証情報の名前を入力します（例：「OpenAI API キー」）。
- 値（実際の API キーまたはトークン）を入力します。このフィールドはパスワード入力として表示されます。
- **「保存」**をクリックします。
[screenshot placeholder: credential editor form with name and value fields]
LLM、埋め込み、またはツールの設定中にインラインで認証情報を作成することもできます。モーダルダイアログを使用すると、現在のページから離れることなく新しい認証情報を追加でき、その認証情報は即座にセレクタードロップダウンに表示されます。
認証情報の編集
- 認証情報リストページで、該当する認証情報の横にある**「編集」**をクリックします。
- 必要に応じて名前または値を更新します。
- **「保存」**をクリックします。
既存の認証情報を表示する場合、リストビューではシークレット値はマスク（********）されます。実際の値は、個々の認証情報の編集ページでのみ表示されます。
認証情報の削除
認証情報が LLM、埋め込み、またはツールによって現在参照されている場合、削除することはできません。使用中の認証情報の削除を試みると、インターフェースにそれを参照しているエンティティの一覧と、その編集ページへのリンクが表示されます。
認証情報を削除するには：
- まず、すべての LLM、埋め込み、またはツールからその認証情報への参照を削除または再割り当てします。
- 認証情報の編集ページに戻ります。
- **「削除」**をクリックし、操作を確認します。
LLM および埋め込みへの認証情報のリンク
LLM モデル
LLM 設定ページ で LLM モデルを設定する際、API キーを直接貼り付ける代わりに、既存の認証情報をドロップダウンから選択できます。実行時に、モデルはリンクされた認証情報からシークレットを解決します。
AWS Bedrock の access_key_id のようなプロバイダー固有のシークレットの場合、認証情報の ID はプロバイダーパラメータ内に保存され、モデルが API リクエストを行う際に透過的に解決されます。
埋め込み定義
埋め込みモデルも同様に動作します。埋め込み定義を設定する際、ドロップダウンから認証情報を選択します。埋め込みモデルは、認証情報またはインライン API キーのいずれかが存在することを検証し、実行時に認証情報の値を使用します。
カスタム AI ツールでの認証情報の使用
カスタム AI ツール は、シークレットに対して契約とバインディングのパターンを使用します。これにより、ツール定義はポータブル（エクスポート/インポート可能）に保たれつつ、シークレットはサイトローカルに保持されます。
ステップ 1：シークレット契約の宣言
ツールを作成または編集する際、認証情報契約にエントリを追加することで、ツールに必要なシークレットを宣言します。各エントリには、文字、数字、アンダースコアのみを使用する単純な識別子であるエイリアスがあります。
ツールエディタページで、**「認証情報の追加」**をクリックして新しい契約エントリを追加し、エイリアス名（例：external_api_key）を付けます。
[screenshot placeholder: tool editor showing credential alias fields and credential selectors]
エイリアス名は [a-zA-Z0-9_] のパターンに一致し、ツール内で一意である必要があります。
ステップ 2：エイリアスへの認証情報のバインド
ツール設定ページで、宣言された各エイリアスの横にあるドロップダウンから既存の認証情報を選択します。これにより、エイリアスと認証情報の間にバインドが作成されます。
バインドは以下の条件を満たすように検証されます。
- 選択された認証情報が存在すること
- エイリアスがツールの契約内で宣言されていること
ステップ 3：JavaScript での実行時シークレットへのアクセス
ツールの JavaScript 内では、secrets.get() API を使用してシークレットにアクセスします。
function invoke(params) {
const apiKey = secrets.get("external_api_key");
const result = http.get("https://api.example.com/data", {
headers: { "Authorization": "Bearer " + apiKey }
});
return JSON.parse(result.body);
}
external_api_key を、ツールの認証情報契約で宣言したエイリアス名に置き換えてください。
ツールを実行するには、宣言されたすべてのエイリアスに必ず認証情報のバインドが必要です。バインドが不足している場合、未バインドのエイリアスをリストしたエラーメッセージで実行がブロックされます。
例：複数の認証情報を持つツール
2 つの異なる API を呼び出すツールを作成すると仮定します。2 つの認証情報契約を宣言します。
| エイリアス | 説明 |
|---|---|
weather_api_key |
天気データ API のキー |
geocode_api_key |
地理コーディング API のキー |
次に、ツール設定ページで、各エイリアスを適切な認証情報にバインドします。
スクリプト内では：
function invoke(params) {
const weatherKey = secrets.get("weather_api_key");
const geocodeKey = secrets.get("geocode_api_key");
const location = http.get(
"https://geocode.example.com/search?q=" + encodeURIComponent(params.city),
{ headers: { "X-Api-Key": geocodeKey } }
);
const coords = JSON.parse(location.body);
const forecast = http.get(
"https://weather.example.com/forecast?lat=" + coords.lat + "&lon=" + coords.lon,
{ headers: { "Authorization": "Bearer " + weatherKey } }
);
return JSON.parse(forecast.body);
}
認証情報の使用状況の追跡
各認証情報は、どこで参照されているかを追跡します。認証情報リストページの**「使用先」**列には、その認証情報を使用しているすべての LLM、埋め込み、またはツールへのリンクが表示されます。
この可視性により、以下が可能になります。
- シークレットをローテーションまたは更新する前に影響を理解する
- 安全に削除できる未使用の認証情報を特定する
- 認証情報に依存するエンティティにすばやく移動する
API リファレンス
すべてのエンドポイントには管理者認証が必要で、パスは /admin/plugins/discourse-ai/ai-secrets 以下です。
| メソッド | パス | 説明 |
|---|---|---|
GET |
/ai-secrets |
すべての認証情報をリスト（値はマスク済み） |
GET |
/ai-secrets/:id |
単一の認証情報を表示（値はマスク解除） |
POST |
/ai-secrets |
新しい認証情報を作成 |
PUT |
/ai-secrets/:id |
認証情報を更新 |
DELETE |
/ai-secrets/:id |
認証情報を削除（使用中の場合は 409 を返す） |
作成および更新用のリクエストボディ：
{
"ai_secret": {
"name": "OpenAI API Key",
"secret": "sk-..."
}
}
作成、更新、削除のすべての操作は、スタッフアクションログに記録されます。シークレット値は機密として扱われ、ログには決して書き込まれません。
インライン API キーからの自動移行
以前にインライン API キーを使用していた既存のインストールは、自動的に移行されます。この移行処理は以下の通りです。
- インライン API キーを持つシードされていないすべての LLM モデルと埋め込み定義を読み取ります。
- API キーとプロバイダーごとに重複排除を行います。2 つのモデルが同じキーとプロバイダーを共有する場合、それらは単一の認証情報を受け取ります。
- 「OpenAI API キー」、「AWS Bedrock API キー」などの自動生成された名前で認証情報レコードを作成します。
- LLM モデルと埋め込み定義レコードを更新し、新しい認証情報を参照するようにします。
- プロバイダーパラメータ内の AWS Bedrock
access_key_id値を処理します。生キーを抽出し、認証情報を作成し、インライン値を認証情報の ID に置き換えます。
この移行はアップグレード時に自動的に実行され、元に戻すことはできません。手動での操作は不要です。
一般的な問題と解決策
「この認証情報は現在使用中であり、削除できません」**
これは、1 つ以上の LLM、埋め込み、またはツールがその認証情報を参照していることを意味します。認証情報リストページの**「使用先」**列を確認し、削除する前にそれらの参照を特定して再割り当てまたは削除してください。
ツール実行時に「必要な認証情報のバインドが不足しています」**
ツールの契約で宣言されたすべての認証情報エイリアスにバインドが必要です。ツールの編集ページを開き、各エイリアスにドロップダウンで認証情報が選択されていることを確認し、保存してください。
認証情報の値が ******** として表示される**
これは期待通りの動作です。セキュリティのため、リストビューではシークレット値はマスクされます。実際の値を表示または編集するには、特定の認証情報の**「編集」**をクリックしてください。
キーをローテーションしたが AI 機能仍然に失敗する**
認証情報の値を更新した後、LLM 設定ページ での LLM テストが成功することを確認してください。新しいキーに異なる権限がある場合、または異なるアカウントに属している場合は、プロバイダーの設定要件を確認してください。
よくある質問
認証情報の代わりにインライン API キーを使用できますか？
従来のインライン API キーは既存の設定で引き続き機能します。ただし、キーのローテーションを簡素化し、重複を減らすため、認証情報を使用することが推奨されます。
認証情報の値は保存時に暗号化されますか？
認証情報の値はデータベースに保存されます。これらは他の機密性の高い Discourse データと同じセキュリティモデルに従います。データベースが適切に保護され、バックアップが適切に処理されていることを確認してください。
認証情報を使用するツールをインポートするとどうなりますか？
ツールのインポートには、認証情報契約のエイリアスが含まれますが、実際のシークレット値は含まれません。ツールをインポートした後、ツールの設定ページで宣言された各エイリアスに対して認証情報を作成または選択する必要があります。
単一の認証情報を複数の LLM で共有できますか？
はい。複数の LLM および埋め込みは、同じ認証情報を参照できます。これは、複数のモデル設定で同じプロバイダーの API キーを使用する場合に特に役立ちます。