면책 조항:
저는 이 통합 기능의 개발자가 아니며, 최선을 다한 친절한 커뮤니티 지원 이상의 지원을 제공할 수 없습니다. 저는 단지 이 설정을 제 사이트에 적용하고 싶었지만 명확한 방법을 찾지 못한 또 다른 사용자일 뿐입니다. 그 과정에서 버그를 발견하여 수정하기 위해 PR을 제출했지만, 이 주제에 대한 제 지식은 다소 제한적입니다.
작동 방식 (아키텍처)
이 설정을 수행하기 전에, 별도의 봇 애플리케이션을 호스팅하거나 서버에서 “봇” 스크립트(예: Node.js 또는 Python 봇)를 실행할 필요가 없음을 이해하는 것이 중요합니다.
이 통합 기능은 Discord Interactions(Webhooks)와 Progressive Edits를 결합하여 스트리밍 AI 경험을 시뮬레이션합니다:
- 사용자 작업: 사용자가 Discord 서버에서
/ask를 입력합니다. - Webhook: Discord가 HTTP POST 요청을 Discourse 서버로 직접 전송합니다.
- 즉각적인 확인 응답: Discourse가 즉시 “검색 중…” 상태를 반환합니다. 이는 Discord의 “Interaction Failed” 타임아웃을 방지합니다.
- 스트리밍 응답: 백그라운드 작업이 AI 답변 생성을 시작합니다. AI가 텍스트를 생성함에 따라 Discourse는 Discord 메시지를 실시간으로 수정하기 위해 빈번한 HTTP PATCH 요청을 전송합니다.
결과: 사용자는 단일 정적 텍스트 블록을 기다리는 대신, ChatGPT와 마찬가지로 답변이 실시간으로 입력되는 것을 볼 수 있습니다.
주요 이점: Discourse가 로직을 내부적으로 처리하므로 유지보수해야 할 추가 인프라가 없습니다. 포럼이 온라인 상태면 봇도 온라인 상태입니다.
이 가이드는 Discord 서버에 Discourse AI 봇을 통합하는 전체 과정을 자세히 설명합니다. 현재 플러그인의 자동 동기화 문제를 우회하기 위해 API를 통해 슬래시 명령을 수동으로 등록하는 구체적인 지침을 포함합니다.
사전 요구 사항
- Discourse 관리자 접근 권한: 자체 호스팅 Discourse 인스턴스의 관리자가여야 합니다.
- Discord 관리자 접근 권한: 대상 Discord 서버에서 “서버 관리” 권한이 있어야 합니다.
- Discourse AI: Discourse 서버에서 활성화되어 있어야 합니다
- 터미널 접근 권한:
curl명령을 실행하기 위해 터미널이 필요합니다.
1. Discord 애플리케이션 생성
- Discord Developer Portal로 이동합니다.
- 오른쪽 상단의 New Application을 클릭합니다.
- 애플리케이션 이름을 지정합니다(예: “Discourse Helper”)하고 Create를 클릭합니다.
- 자격 증명 복사: General Information 페이지에서 다음 정보를 찾아 나중에 사용하도록 저장합니다:
2. 봇 사용자 구성
-
왼쪽 사이드바 메뉴에서 Bot을 클릭합니다.
-
Reset Token을 클릭합니다.
-
특수 권한 인텐트(Privileged Intents) 활성화:
- “Privileged Gateway Intents” 섹션으로 스크롤합니다.
- Message Content Intent를 ON으로 전환합니다. (이것은 봇이 응답해야 할 메시지를 읽을 수 있도록 합니다.)
-
Save Changes를 클릭합니다.
3. Discourse 설정 구성
-
Discourse 관리자 패널에 로그인합니다.
-
Admin → Plugins → AI → Features로 이동합니다.
-
"discord"를 검색하고 편집을 클릭합니다:
-
세부 정보를 입력합니다
AI Discord app ID:=ApplicationId=를 붙여넣습니다AI Discord app public key:=PublicKey=를 붙여넣습니다
-
Discord 서버 허용:
- Discord 앱을 열고 개발자 모드를 활성화합니다(User Settings → Advanced → Developer Mode).
- 사이드바의 서버 아이콘을 우클릭하고 Copy Server ID를 선택합니다.
- Discourse 설정에서 이 ID를
AI Discord allowed guilds필드에 붙여넣습니다.
4. Interactions 엔드포인트 설정
- 엔드포인트 URL을 구성합니다:
=ForumUrl=/discourse-ai/discord/interactions - Discord Developer Portal로 돌아갑니다.
- General Information 페이지에서 Interactions Endpoint URL로 스크롤합니다.
- URL을 붙여넣고 Save Changes를 클릭합니다.
- 성공: Discord가 테스트 신호를 전송합니다. 오류 없이 저장되면 Discourse 인스턴스가 서명을 성공적으로 검증한 것입니다.
- 실패: 오류가 발생하면 Discourse 설정에서
AI Discord app ID와AI Discord app public key가 올바르게 저장되었는지 확인하십시오.
5. 봇 초대
- Developer Portal에서 사이드바의 Installation을 클릭합니다.
- Scopes:
bot및applications.commands상자를 선택합니다. - Bot Permissions: 다음 항목을 선택합니다:
- Send Messages
- Embed Links
- Attach Files
- Read Message History
- 페이지 상단의 Installation Link를 복사합니다.
- 브라우저 탭에서 이 URL을 열고 봇이 서버에 참여하도록 권한을 부여합니다.
6. 슬래시 명령 등록 (수동 API 호출)
중요: 명령 매개변수 이름은 query여야 합니다.
Mac / Linux (Bash)용
curl -X POST "https://discord.com/api/v10/applications/=ApplicationId=/commands" \
-H "Authorization: Bot =BotToken=" \
-H "Content-Type: application/json" \
-d '{
"name": "ask",
"description": "Ask the AI a question",
"options": [
{
"name": "query",
"description": "What is your question?",
"type": 3,
"required": true
}
]
}'
- 성공 응답: 새 명령의 ID가 포함된 JSON 응답을 받아야 합니다.
- 오류 401? Authorization 헤더에서 토큰 앞에
Bot(공백 포함) 단어가 있는지 확인하십시오.
7. 검증
- Discord 서버를 엽니다.
- 텍스트 채널에서
/ask를 입력합니다. - 명령 메뉴가 나타납니다.
/ask를 선택하고query필드에 질문을 입력합니다. - 예상 동작:
- 즉시: 봇이 "검색 중…"이라고 응답합니다.
- 몇 초 후: 메시지가 AI의 답변으로 업데이트됩니다.
문제 해결
| 오류 | 원인 | 해결책 |
|---|---|---|
| 401 Unauthorized (Curl에서) | 잘못된 토큰 형식 | 헤더가 Authorization: Bot =BotToken=인지 확인하십시오. General 탭이 아닌 Bot 탭의 토큰을 사용하십시오. |
| Job Exception: context must be an instance of BotContext | 잘못된 페이로드 | 최신 버전으로 업데이트되어 있는지 확인하십시오. 이 문제는 FIX: Discord Bot crash due to missing BotContext in PersonaReplier - Pull Request #36429#issuecomment-3610843271%EC%97%90%EC%84%9C - discourse/discourse - GitHub 수정되었습니다 |