管理 AI 凭证

[sam (Sam Saffron)]

本指南介绍如何在 Discourse AI 插件中，跨大语言模型（LLM）、嵌入模型和自定义 AI 工具创建、管理和使用 AI 凭据（共享密钥）。

所需用户级别：管理员

摘要

AI 凭据提供了一种集中且安全的方式来管理 Discourse AI 配置中的身份验证密钥（如 API 密钥）。您无需将原始 API 密钥逐个粘贴到每个 LLM 模型、嵌入定义或自定义工具中，只需创建一次凭据，即可在需要时随处引用。

当您轮换密钥（例如您的 OpenAI API 密钥）时，只需在一处进行更新，所有使用该凭据的 LLM、嵌入或工具都会自动获取更改。

本文档涵盖以下内容：

• 创建和管理凭据
• 将凭据链接到 LLM 和嵌入模型
• 在自定义 AI 工具中使用凭据
• 删除保护与凭据生命周期
• 用于以编程方式管理凭据的 API

什么是凭据？

凭据是存储在 Discourse AI 中央的命名、可重用的密钥。它包含两个主要字段：

字段	描述
名称	唯一且人类可读的标签（例如“OpenAI API 密钥”）。最多 100 个字符。
值	实际的密钥（API 密钥、令牌等）。最多 10,000 个字符。

凭据可被以下三类实体引用：

• LLM 模型 — 作为主要 API 密钥
• 嵌入定义 — 作为主要 API 密钥
• 自定义 AI 工具 — 作为从 JavaScript 访问的命名密钥绑定

此外，某些类型为“密钥”的 LLM 提供商参数（例如 AWS Bedrock 的 access_key_id）也会引用凭据。

创建和管理凭据

访问凭据页面

导航至 管理 → 插件 → Discourse AI → 凭据，或直接访问 /admin/plugins/discourse-ai/ai-secrets。

[screenshot placeholder: credentials list page showing name, used-by, and edit button columns]

创建新凭据

1. 在凭据页面，点击 “新建凭据”。
2. 输入凭据的 名称（例如“OpenAI API 密钥”）。
3. 输入 值 — 实际的 API 密钥或令牌。此字段显示为密码输入框。
4. 点击 “保存”。

[screenshot placeholder: credential editor form with name and value fields]

您也可以在配置 LLM、嵌入或工具时内联创建凭据。一个模态对话框允许您在不离开当前页面的情况下添加新凭据，新凭据会立即出现在选择器下拉菜单中。

编辑凭据

1. 在凭据列表页面，点击凭据旁边的 “编辑”。
2. 根据需要更新 名称 或 值。
3. 点击 “保存”。

查看现有凭据时，列表视图中的密钥值会被掩盖（********）。实际值仅在单个凭据的编辑页面上显示。

删除凭据

如果凭据当前被任何 LLM、嵌入或工具引用，则无法删除该凭据。如果您尝试删除正在使用的凭据，界面会显示一条消息，列出引用它的实体，并提供指向其编辑页面的链接。

要删除凭据：

1. 首先，从任何 LLM、嵌入或工具中移除或重新分配所有对该凭据的引用。
2. 返回到该凭据的编辑页面。
3. 点击 “删除” 并确认操作。

将凭据链接到 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 替换为您在工具密钥合约中声明的别名名称。

在工具可以运行之前，所有声明的别名必须具有凭据绑定。如果缺少任何绑定，执行将被阻止，并显示列出未绑定别名的错误消息。

示例：使用多个凭据的工具

假设您正在构建一个调用两个不同 API 的工具。声明两个密钥合约：

别名	描述
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 密钥",
    "secret": "sk-..."
  }
}

所有创建、更新和删除操作都会记录到员工操作日志中。密钥值被视为敏感信息，绝不会写入日志。

从内联 API 密钥自动迁移

以前使用内联 API 密钥的现有安装将自动迁移。迁移过程如下：

1. 读取所有具有内联 API 密钥的非种子 LLM 模型和嵌入定义。
2. 按 API 密钥和提供商去重 — 如果两个模型共享相同的密钥和提供商，它们将共用一个凭据。
3. 创建具有自动生成名称（如“OpenAI API 密钥”、“AWS Bedrock API 密钥”等）的凭据记录。
4. 更新 LLM 模型和嵌入定义记录以引用新凭据。
5. 处理 AWS Bedrock access_key_id 值 — 提取原始密钥，创建凭据，并将内联值替换为凭据的 ID。

此迁移在升级时自动运行，且不可逆转。无需手动操作。

常见问题及解决方案

“此凭据当前正在使用中，无法删除”

这意味着一个或多个 LLM、嵌入或工具引用了该凭据。请检查凭据列表页面中的 “被谁使用” 列，以识别并重新分配或移除这些引用，然后再进行删除。

运行工具时出现“缺少必需的凭据绑定”

工具合约中声明的所有密钥别名都必须有绑定。打开工具的编辑页面，验证每个别名是否在下拉菜单中选择了凭据，然后保存。

凭据值显示为 ********

这是预期行为。出于安全考虑，列表视图中的密钥值会被掩盖。要查看或编辑实际值，请点击特定凭据的 “编辑”。

已轮换密钥但 AI 功能仍失败

更新凭据值后，请验证 LLM 测试（在 LLM 设置页面 上）是否通过。如果新密钥具有不同的权限或属于不同的账户，请检查提供商的配置要求。

常见问题解答

我仍然可以使用内联 API 密钥而不是凭据吗？
传统的内联 API 密钥继续适用于现有配置。但是，凭据是推荐的方法，因为它们简化了密钥轮换并减少了重复。

凭据值在静止状态下是否加密？
凭据值存储在数据库中。它们遵循与其他敏感 Discourse 数据相同的安全模型。请确保您的数据库得到适当保护，并且备份得到妥善处理。

当我导入使用凭据的工具时会发生什么？
工具导入包括密钥合约别名，但不包括实际的密钥值。导入工具后，您需要在工具的配置页面上为每个声明的别名创建或选择凭据。

我可以跨多个 LLM 共享单个凭据吗？
可以。多个 LLM 和嵌入可以引用同一个凭据。当您在多个模型配置中使用相同的提供商 API 密钥时，这特别有用。

其他资源

• Discourse AI - Large Language Model (LLM) settings page
• AI bot - Custom tools
• Discourse AI - AI bot
• Configure API Keys for OpenAI
• Configure API Keys for Anthropic
• Configuring Amazon Bedrock services
• Configuring OpenRouter language models