Это руководство описывает создание, управление и использование учетных данных ИИ (общих секретов) для больших языковых моделей (LLM), моделей векторизации (embedding) и пользовательских инструментов ИИ в плагине Discourse AI.
Требуемый уровень доступа пользователя: Администратор
Краткое содержание
Учетные данные ИИ предоставляют централизованный и безопасный способ управления секретными данными аутентификации, такими как API-ключи, в рамках конфигурации Discourse AI. Вместо того чтобы вставлять сырые API-ключи в каждую модель LLM, определение векторизации или пользовательский инструмент по отдельности, вы создаете учетные данные один раз и ссылаетесь на них везде, где это необходимо.
При ротации ключа (например, вашего API-ключа OpenAI) вы обновляете его в одном месте, и любая модель LLM, векторизация или инструмент, использующие эти учетные данные, автоматически подхватывают изменения.
Эта документация охватывает:
- Создание и управление учетными данными
- Привязку учетных данных к моделям LLM и моделям векторизации
- Использование учетных данных в пользовательских инструментах ИИ
- Защиту от удаления и жизненный цикл учетных данных
- API для программного управления учетными данными
Что такое учетные данные?
Учетные данные — это именованный, повторно используемый секрет, хранящийся централизованно в Discourse AI. Он состоит из двух основных полей:
| Поле | Описание |
|---|---|
| Имя | Уникальная, понятная человеку метка (например, «API-ключ OpenAI»). Максимум 100 символов. |
| Значение | Собственно секрет (API-ключ, токен и т. д.). Максимум 10 000 символов. |
На учетные данные могут ссылаться три типа сущностей:
- Модели LLM — в качестве основного API-ключа
- Определения векторизации — в качестве основного API-ключа
- Пользовательские инструменты ИИ — в качестве именованных привязок секретов, доступных из JavaScript
Кроме того, определенные параметры провайдеров LLM типа «секрет» (например, access_key_id для AWS Bedrock) также ссылаются на учетные данные.
Создание и управление учетными данными
Доступ к странице учетных данных
Перейдите в раздел Администрирование → Плагины → Discourse AI → Учетные данные или напрямую откройте /admin/plugins/discourse-ai/ai-secrets.
[ссылка на скриншот: страница списка учетных данных с колонками «Имя», «Используется в» и кнопкой «Изменить»]
Создание новых учетных данных
- На странице учетных данных нажмите кнопку «Создать учетные данные».
- Введите Имя для учетных данных (например, «API-ключ OpenAI»).
- Введите Значение — фактический API-ключ или токен. Это поле отображается как поле ввода пароля.
- Нажмите кнопку «Сохранить».
[ссылка на скриншот: форма редактора учетных данных с полями «Имя» и «Значение»]
Вы также можете создавать учетные данные непосредственно при настройке модели LLM, векторизации или инструмента. Всплывающее окно позволяет добавить новые учетные данные, не покидая текущую страницу, и они сразу же появляются в выпадающем списке выбора.
Редактирование учетных данных
- На странице списка учетных данных нажмите кнопку «Изменить» рядом с нужными учетными данными.
- При необходимости обновите Имя или Значение.
- Нажмите кнопку «Сохранить».
При просмотре существующих учетных данных секретное значение маскируется (********) в списке. Фактическое значение отображается только на странице редактирования конкретных учетных данных.
Удаление учетных данных
Учетные данные нельзя удалить, если на них ссылается какая-либо модель LLM, векторизация или инструмент. Если вы попытаетесь удалить используемые учетные данные, интерфейс покажет сообщение со списком сущностей, которые на них ссылаются, и ссылками на их страницы редактирования.
Чтобы удалить учетные данные:
- Сначала удалите или переназначьте все ссылки на учетные данные из любых моделей LLM, векторизаций или инструментов.
- Вернитесь на страницу редактирования учетных данных.
- Нажмите кнопку «Удалить» и подтвердите действие.
Привязка учетных данных к моделям LLM и векторизации
Модели LLM
При настройке модели LLM на странице настроек LLM вы можете выбрать существующие учетные данные из выпадающего списка вместо того, чтобы вставлять API-ключ напрямую. Во время выполнения модель получает секрет из связанной учетной записи.
Для специфичных для провайдера секретов, таких как access_key_id для AWS Bedrock, идентификатор учетных данных хранится внутри параметров провайдера и прозрачно разрешается при выполнении моделью запросов к API.
Определения векторизации
Модели векторизации работают аналогичным образом. При настройке определения векторизации выберите учетные данные из выпадающего списка. Модель векторизации проверяет наличие либо учетных данных, либо встроенного API-ключа и использует значение учетных данных во время выполнения.
Использование учетных данных в пользовательских инструментах ИИ
Пользовательские инструменты ИИ используют паттерн контракта и привязки для секретов, что делает определение инструмента переносимым (экспортируемым/импортируемым), в то время как секреты остаются локальными для сайта.
Шаг 1: Объявление контрактов секретов
При создании или редактировании инструмента вы объявляете, какие секреты требуются инструменту, добавляя записи в раздел контракты учетных данных. Каждая запись имеет алиас — простой идентификатор, состоящий из букв, цифр и знаков подчеркивания.
На странице редактора инструментов нажмите кнопку «Добавить учетные данные», чтобы добавить новую запись контракта и задать ей имя алиаса, например external_api_key.
[ссылка на скриншот: редактор инструментов с полями алиасов учетных данных и селекторами]
Имена алиасов должны соответствовать шаблону [a-zA-Z0-9_] и быть уникальными в пределах инструмента.
Шаг 2: Привязка учетных данных к алиасам
Рядом с каждым объявленным алиасом на странице конфигурации инструмента выберите существующие учетные данные из выпадающего списка. Это создает привязку между алиасом и учетными данными.
Проверка привязки гарантирует:
- Наличие выбранной учетной записи
- Объявление алиаса в контрактах инструмента
Шаг 3: Доступ к секретам во время выполнения в JavaScript
Внутри JavaScript инструмента используйте API secrets.get() для доступа к секретам:
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": "API-ключ OpenAI",
"secret": "sk-..."
}
}
Все операции создания, обновления и удаления регистрируются в журнале действий персонала. Значения секретов считаются конфиденциальными и никогда не записываются в логи.
Автоматическая миграция встроенных API-ключей
Существующие установки, которые ранее использовали встроенные API-ключи, автоматически мигрируются. Миграция включает:
- Чтение всех моделей LLM и определений векторизации, не являющихся seed-данными, которые имеют встроенный API-ключ.
- Удаление дубликатов по API-ключу и провайдеру — если две модели используют один и тот же ключ и провайдера, им назначается одна учетная запись.
- Создание записей учетных данных с автоматически сгенерированными именами, такими как «API-ключ OpenAI», «API-ключ AWS Bedrock» и т. д.
- Обновление записей моделей LLM и определений векторизации для ссылки на новые учетные данные.
- Обработку значений
access_key_idAWS Bedrock в параметрах провайдера — извлечение сырого ключа, создание учетных данных и замена встроенного значения на идентификатор учетных данных.
Эта миграция выполняется автоматически при обновлении и является необратимой. Никаких ручных действий не требуется.
Распространенные проблемы и решения
«Эти учетные данные в настоящее время используются и не могут быть удалены»
Это означает, что одна или несколько моделей LLM, векторизаций или инструментов ссылаются на учетные данные. Проверьте колонку «Используется в» на странице списка учетных данных, чтобы выявить и переназначить или удалить эти ссылки перед удалением.
«Отсутствуют обязательные привязки учетных данных» при запуске инструмента
Все алиасы учетных данных, объявленные в контрактах инструмента, должны иметь привязки. Откройте страницу редактирования инструмента, убедитесь, что для каждого алиаса выбраны учетные данные в выпадающем списке, и сохраните изменения.
Значение учетных данных отображается как ********
Это ожидаемое поведение. Секретные значения маскируются в списках в целях безопасности. Чтобы просмотреть или изменить фактическое значение, нажмите кнопку «Изменить» для конкретных учетных данных.
Ключ был ротирован, но функции ИИ все еще не работают
После обновления значения учетных данных убедитесь, что тест LLM (на странице настроек LLM) пройден успешно. Если новый ключ имеет другие разрешения или принадлежит другой учетной записи, проверьте требования конфигурации провайдера.
Часто задаваемые вопросы (FAQ)
Могу ли я по-прежнему использовать встроенные API-ключи вместо учетных данных?
Устаревшие встроенные API-ключи продолжают работать для существующих конфигураций. Однако учетные данные являются рекомендуемым подходом, поскольку они упрощают ротацию ключей и снижают дублирование.
Зашифрованы ли значения учетных данных при хранении?
Значения учетных данных хранятся в базе данных. Они следуют той же модели безопасности, что и другие конфиденциальные данные Discourse. Убедитесь, что ваша база данных должным образом защищена, а резервные копии обрабатываются соответствующим образом.
Что происходит при импорте инструмента, использующего учетные данные?
При импорте инструмента включаются алиасы контрактов учетных данных, но не фактические значения секретов. После импорта инструмента вам нужно будет создать или выбрать учетные данные для каждого объявленного алиаса на странице конфигурации инструмента.
Могу ли я использовать одни и те же учетные данные для нескольких моделей LLM?
Да. Несколько моделей LLM и векторизаций могут ссылаться на одни и те же учетные данные. Это особенно полезно, если вы используете один и тот же API-ключ провайдера в нескольких конфигурациях моделей.