AI 자격 증명 관리

sam · 3월 2, 2026, 4:28오전

이 가이드는 Discourse AI 플러그인에서 LLM, 임베딩 모델, 사용자 정의 AI 도구를 아우르는 AI 자격 증명(공유 시크릿) 생성, 관리 및 사용법을 다룹니다.

필요한 사용자 권한: 관리자

요약

AI 자격 증명은 Discourse AI 구성 전반에 걸쳐 API 키와 같은 인증 시크릿을 중앙 집중적이고 안전하게 관리하는 방법을 제공합니다. 각 LLM 모델, 임베딩 정의, 사용자 정의 도구에 원시 API 키를 직접 붙여 넣는 대신, 자격 증명을 한 번 생성한 뒤 필요한 곳에서 참조할 수 있습니다.

키를 회전(Rotate)할 때(예: OpenAI API 키 변경), 한 곳에서만 업데이트하면 해당 자격 증명을 사용하는 모든 LLM, 임베딩, 도구가 자동으로 변경 사항을 반영합니다.

이 문서에서는 다음 내용을 다룹니다:

자격 증명 생성 및 관리
LLM 및 임베딩 모델에 자격 증명 연결
사용자 정의 AI 도구에서 자격 증명 사용
삭제 방지 및 자격 증명 라이프사이클
자격 증명을 프로그래매틱하게 관리하는 API

자격 증명(Credential)이란?

자격 증명은 Discourse AI에 중앙 집중식으로 저장되는 이름이 지정된 재사용 가능한 시크릿입니다. 두 가지 주요 필드가 있습니다:

필드	설명
이름 (Name)	고유한 사람이 읽을 수 있는 라벨(예: “OpenAI API Key”). 최대 100자.
값 (Value)	실제 시크릿(API 키, 토큰 등). 최대 10,000자.

자격 증명은 다음 세 가지 유형의 엔티티에 의해 참조될 수 있습니다:

LLM 모델 — 기본 API 키로 사용
임베딩 정의 — 기본 API 키로 사용
사용자 정의 AI 도구 — JavaScript에서 접근하는 이름이 지정된 시크릿 바인딩으로 사용

추가로, “secret” 유형의 특정 LLM 제공자 매개변수(예: AWS Bedrock의 access_key_id)도 자격 증명을 참조합니다.

자격 증명 생성 및 관리

자격 증명 페이지 접근

관리자(Admin) → 플러그인(Plugins) → Discourse AI → 자격 증명(Credentials) 경로로 이동하거나, /admin/plugins/discourse-ai/ai-secrets 주소를 직접 방문하세요.

[스크린샷 자리표시: 이름, 사용처, 편집 버튼 열이 표시된 자격 증명 목록 페이지]

새 자격 증명 생성

자격 증명 페이지에서 **“새 자격 증명(New credential)”**을 클릭합니다.
자격 증명의 **이름(Name)**을 입력합니다(예: “OpenAI API Key”).
**값(Value)**을 입력합니다. 이는 실제 API 키 또는 토큰입니다. 이 필드는 비밀번호 입력 필드로 표시됩니다.
**“저장(Save)”**을 클릭합니다.

[스크린샷 자리표시: 이름과 값 필드가 있는 자격 증명 편집기 폼]

LLM, 임베딩 또는 도구를 구성하는 동안에도 인라인으로 자격 증명을 생성할 수 있습니다. 모달 대화상자를 통해 현재 페이지를 떠나지 않고 새 자격 증명을 추가할 수 있으며, 해당 자격 증명은 즉시 선택 드롭다운에 나타납니다.

자격 증명 편집

자격 증명 목록 페이지에서 해당 자격 증명 옆의 **“편집(Edit)”**을 클릭합니다.
필요에 따라 이름(Name) 또는 **값(Value)**을 업데이트합니다.
**“저장(Save)”**을 클릭합니다.

기존 자격 증명을 볼 때, 시크릿 값은 목록 보기에서 마스킹(********) 처리됩니다. 실제 값은 해당 자격 증명의 개별 편집 페이지에서만 표시됩니다.

자격 증명 삭제

자격 증명은 현재 LLM, 임베딩 또는 도구 중 하나에 의해 참조되고 있는 경우 삭제할 수 없습니다. 사용 중인 자격 증명을 삭제하려고 하면, 해당 자격 증명을 참조하는 엔티티 목록과 각 엔티티의 편집 페이지 링크가 포함된 메시지가 표시됩니다.

자격 증명을 삭제하려면:

먼저 LLM, 임베딩 또는 도구에서 해당 자격 증명에 대한 모든 참조를 제거하거나 재할당합니다.
자격 증명 편집 페이지로 돌아갑니다.
**“삭제(Delete)”**를 클릭하고 작업을 확인합니다.

LLM 및 임베딩에 자격 증명 연결

LLM 모델

LLM 설정 페이지에서 LLM 모델을 구성할 때, API 키를 직접 붙여 넣는 대신 드롭다운에서 기존 자격 증명을 선택할 수 있습니다. 런타임에 모델은 연결된 자격 증명에서 시크릿을 해석합니다.

제공자별 시크릿(예: AWS Bedrock의 access_key_id)의 경우, 자격 증명의 ID가 제공자 매개변수 안에 저장되며, 모델이 API 요청을 수행할 때 투명하게 해석됩니다.

임베딩 정의

임베딩 모델도 동일한 방식으로 작동합니다. 임베딩 정의를 구성할 때 드롭다운에서 자격 증명을 선택합니다. 임베딩 모델은 자격 증명 또는 인라인 API 키가 존재하는지 검증하고, 런타임에 자격 증명의 값을 사용합니다.

사용자 정의 AI 도구에서 자격 증명 사용

사용자 정의 AI 도구는 시크릿을 위해 계약(Contract) 및 바인딩(Binding) 패턴을 사용합니다. 이를 통해 도구 정의는 이동 가능하게(내보내기/가져오기 가능) 유지되는 동안 시크릿은 사이트 로컬에 유지됩니다.

1단계: 시크릿 계약 선언

도구를 생성하거나 편집할 때, **자격 증명 계약(credential contracts)**에 항목을 추가하여 도구가 필요한 시크릿을 선언합니다. 각 항목에는 **별칭(alias)**이 있으며, 이는 문자, 숫자, 밑줄을 사용하는 간단한 식별자입니다.

도구 편집기 페이지에서 **“자격 증명 추가(Add credential)”**를 클릭하여 새 계약 항목을 추가하고, 예를 들어 external_api_key와 같은 별칭 이름을 부여합니다.

[스크린샷 자리표시: 자격 증명 별칭 필드와 자격 증명 선택기가 표시된 도구 편집기]

별칭 이름은 [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);
}

자격 증명 사용 추적

각 자격 증명은 어디에서 참조되는지 추적합니다. 자격 증명 목록 페이지의 “사용처(Used by)” 열에는 현재 해당 자격 증명을 사용하는 모든 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` 반환)

생성 및 업데이트를 위한 요청 본문(Request body):

{
  "ai_secret": {
    "name": "OpenAI API Key",
    "secret": "sk-..."
  }
}

모든 생성, 업데이트, 삭제 작업은 스태프 액션 로그에 기록됩니다. 시크릿 값은 민감한 정보로 취급되어 로그에 기록되지 않습니다.

인라인 API 키에서 자동 마이그레이션

이전에 인라인 API 키를 사용했던 기존 설치 환경은 자동으로 마이그레이션됩니다. 마이그레이션 과정은 다음과 같습니다:

인라인 API 키가 있는 모든 시드되지 않은 LLM 모델 및 임베딩 정의를 읽습니다.
API 키 및 제공자를 기준으로 **중복 제거(Deduplicate)**합니다 — 두 모델이 동일한 키와 제공자를 공유하면 단일 자격 증명을 부여받습니다.
“OpenAI API Key”, “AWS Bedrock API Key” 등과 같은 자동 생성된 이름으로 자격 증명 레코드를 생성합니다.
LLM 모델 및 임베딩 정의 레코드를 업데이트하여 새 자격 증명을 참조하도록 합니다.
제공자 매개변수 내 AWS Bedrock access_key_id 값을 처리합니다 — 원시 키를 추출하고 자격 증명을 생성한 뒤, 인라인 값을 자격 증명의 ID로 대체합니다.

이 마이그레이션은 업그레이드 시 자동으로 실행되며 되돌릴 수 없습니다. 수동 작업이 필요하지 않습니다.

일반적인 문제 및 해결 방법

“이 자격 증명은 현재 사용 중이므로 삭제할 수 없습니다”

이는 하나 이상의 LLM, 임베딩 또는 도구가 해당 자격 증명을 참조하고 있음을 의미합니다. 삭제하기 전에 자격 증명 목록 페이지의 “사용처(Used by)” 열을 확인하여 해당 참조를 식별하고 재할당하거나 제거하세요.

도구 실행 시 “필수 자격 증명 바인딩 누락”

도구의 계약에 선언된 모든 자격 증명 별칭에는 바인딩이 있어야 합니다. 도구 편집 페이지를 열어 각 별칭에 드롭다운에서 자격 증명이 선택되었는지 확인한 후 저장하세요.

자격 증명 값이 `********`로 표시됨

이것은 예상되는 동작입니다. 보안상의 이유로 시크릿 값은 목록 보기에서 마스킹 처리됩니다. 실제 값을 보거나 편집하려면 특정 자격 증명에서 **“편집(Edit)”**을 클릭하세요.

키를 회전했는데도 AI 기능이 여전히 실패함

자격 증명의 값을 업데이트한 후, LLM 설정 페이지의 LLM 테스트가 통과하는지 확인하세요. 새 키가 다른 권한을 가지고 있거나 다른 계정에 속하는 경우, 제공자의 구성 요구 사항을 확인하세요.

FAQ

자격 증명 대신 인라인 API 키를 계속 사용할 수 있나요?
레거시 인라인 API 키는 기존 구성에 대해 계속 작동합니다. 그러나 자격 증명은 키 회전을 단순화하고 중복을 줄이기 때문에 권장되는 접근 방식입니다.

자격 증명 값은 저장 시 암호화되나요?
자격 증명 값은 데이터베이스에 저장됩니다. 다른 민감한 Discourse 데이터와 동일한 보안 모델을 따릅니다. 데이터베이스가 적절히 보호되고 백업이 적절히 처리되도록 하세요.

자격 증명을 사용하는 도구를 가져오면 어떻게 되나요?
도구 가져오기에는 자격 증명 계약의 별칭은 포함되지만 실제 시크릿 값은 포함되지 않습니다. 도구를 가져온 후, 도구 구성 페이지에서 선언된 각 별칭에 대해 자격 증명을 생성하거나 선택해야 합니다.

단일 자격 증명을 여러 LLM에 공유할 수 있나요?
네. 여러 LLM과 임베딩이 동일한 자격 증명을 참조할 수 있습니다. 이는 여러 모델 구성에서 동일한 제공자 API 키를 사용할 때 특히 유용합니다.

글		댓글	조회수
Announcing AI credentials Announcements ai	3	330	3월 2, 2026
Configure API Keys for Anthropic Integrations how-to , ai	0	1741	10월 3, 2023
Configure API Keys for Azure OpenAI Integrations how-to , ai	1	2276	1월 18, 2024
Feature request: improve Discourse AI LLM setup (model discovery) and add AI config import/export Feature ai	0	126	1월 26, 2026
Configure API Keys for OpenAI Integrations how-to , ai	11	4073	11월 11, 2024