원바오
Hermes를 Yuanbao, Tencent의 엔터프라이즈 메시징 플랫폼에 연결하세요. 어댑터는 실시간 메시지 전달을위한 WebSocket Gateway를 사용하고 직접 지원 () 및 그룹 대화.
Yuanbao는 Tencent와 기업 환경에서 주로 사용되는 기업 메시징 플랫폼입니다. 실시간 커뮤니케이션, HMAC 기반 인증을 위한 WebSocket을 사용하고, 이미지, 파일 및 음성 메시지를 포함한 풍부한 미디어를 지원합니다. 주요 특징
필수품
- 봇 생성 권한을 가진 Yuanbao 계정
- Yuanbao APP ID 및 APP SECRET (플랫폼 관리자에서)
- 파이썬 패키지:
websockets및httpx - 매체 지원을 위해:
aiofiles
필요한 의존도를 설치하세요:
사이트맵
설치
##1. Yuanbao의 Bot 만들기
- https://yuanbao.tencent.com/
- 앱에서 ** PAI → 내 봇**로 이동하여 새로운 봇을 만듭니다.
- 봇이 생성되면 APP ID및APP SECRET를 복사합니다.
##2. 설정 마법사를 실행
Yuanbao를 구성하는 가장 쉬운 방법은 상호 작용하는 체제를 통해 입니다:
hermes gateway setup
**Yuanbao ** 프롬프트 할 때. 마법사는:
- APP ID 요청
- APP SECRET 요청
- 설정을 자동으로 저장
WebSocket URL 및 API 도메인에는 내장 된 감지 가능한 기본값이 있습니다. APP ID 및 APP SECRET를 제공해야 합니다. 주요 특징
##3. 환경 변수 구성
초기 설정 후 ~/.hermes/.env의 이러한 변수를 확인합니다.
사이트맵
##4. 게이트웨이 시작
사이트맵
어댑터는 Yuanbao WebSocket Gateway에 연결되며 HMAC 서명을 사용하여 인증하고 메시지를 처리하세요.
특징
- WebSocket Gateway - 실시간 양방향 통신
- HMAC 인증 - APP ID/APP SECRET와 보안 요청 서명
- ** 메시징** - 직접 사용자 로봇 대화
- 그룹 메시징 - 그룹 채팅의 대화
- Media support - COS (Cloud Object Storage)를 통해 이미지, 파일 및 음성 메시지 -Markdown formatting — 메시지는 Yuanbao의 크기 제한을 위해 chunked 입니다 -Message deduplication - 같은 메시지의 중복 처리 방지
- Heartbeat/keep-alive - WebSocket 연결 안정성을 유지 -Typing 지시자 — 에이전트 과정 도중 “typing...” 상태를 보여줍니다 -Automatic reconnection - exponential backoff와 WebSocket 단자 처리
- **그룹 정보 쿼리 ** — 그룹 세부 및 회원 목록 검색
- Sticker/Emoji 지원 - 대화에서 TIMFaceElem 스티커와 이모티콘을 보내십시오
- Auto-sethome - 봇을 메시지하는 첫 번째 사용자는 홈 채널 소유자로 자동으로 설정됩니다.
- **Slow-response 알림 ** - 에이전트가 예상보다 더 이상 소요될 때 대기 메시지를 보냅니다.
구성 옵션
채팅 ID 형식
Yuanbao는 대화 유형에 따라 prefixed 식별자를 사용합니다:
| 채팅 타입 | 형식 | 보기 |
|---|---|---|
| 연락처() | direct:<account> | direct:user123 |
| 그룹 메시지 | group:<group_code> | group:grp456 |
미디어 업로드
Yuanbao 어댑터는 COS (Tencent Cloud Object Storage)를 통해 미디어 업로드를 자동으로 처리합니다.
-Images: JPEG, PNG, GIF, WebP 지원
- ** 파일**: 모든 일반적인 문서 유형 지원 -Voice: WAV, MP3, OGG 지원
Media URL은 SSRF 공격을 방지하기 위해 업로드하기 전에 자동으로 검증되고 다운로드됩니다.
홈 채널
모든 Yuanbao 채팅 (DM 또는 그룹)에서 /sethome 명령을 사용하여 홈 채널로 지정하세요. Scheduled task (cron job)는 이 채널에 결과를 제공합니다.
홈 채널이 구성되지 않은 경우, 봇을 메시지하는 첫 번째 사용자는 홈 채널 소유자로 자동으로 설정됩니다. 현재 홈 채널이 그룹 채팅이라면, 첫 번째 DM은 직접 채널로 업그레이드합니다. 주요 특징
~/.hermes/.env에서 수동으로 설정할 수 있습니다.
YUANBAO_HOME_CHANNEL=direct:user_account_id
# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"
예제: 홈 채널 설정
- Yuanbao의 봇과 대화 시작
- 명령을 보내십시오:
/sethome - 봇 응답: ID [chat id]로 "홈 채널 설정. Cron 작업은이 위치에 전달됩니다."
- 미래 cron 작업 및 알림이 채널로 전송됩니다.
예제: Cron 작업 납품
cron 작업 만들기:
/cron "0 9 * * *" Check server status
예정된 산출은 당신의 Yuanbao 집 수로에 매일 9 AM에 배달될 것입니다.
사용법 팁
대화 시작
Yuanbao의 봇에 메시지 보내기:
사이트맵
봇은 같은 대화 스레드에 응답합니다.
유효한 명령
모든 표준 헤르메스 명령은 Yuanbao에서 작동합니다.
| 명령 | 설명 |
|---|---|
/new | 신선한 대화 시작 |
/model [provider:model] | 모델 표시 또는 변경 |
/sethome | 홈 채널로 채팅 설정 |
/status | 세션 안내 |
/help | 사용 가능한 명령어 보기 |
파일 보내기
봇에 파일을 보내려면 Yuanbao 채팅에서 직접 첨부하세요. 봇은 자동으로 파일 첨부 파일을 다운로드하고 처리합니다.
첨부 파일도 포함할 수 있습니다:
사이트맵
수신 파일
봇을 요청하면 파일을 만들거나 내보내면 Yuanbao 채팅에 직접 파일을 보냅니다.
문제 해결
Bot은 온라인이지만 메시지에 응답하지 않습니다.
** 원인**: WebSocket Handhake에서 인증이 실패했습니다.
Fix:
- APP ID 및 APP SECRET를 검증합니다.
- WebSocket URL이 접근 가능
- 봇 계정이 적절한 권한이 있는지 확인하세요.
- 검토 게이트웨이 로그:
tail -f ~/.hermes/logs/gateway.log
"연결 거부" 오류
** 원인**: WebSocket URL은 부정확하거나 부정확합니다.
Fix:
- WebSocket URL 형식 확인 (
wss://로 시작) - Yuanbao API 도메인에 네트워크 연결 확인
- 방화벽을 확인하려면 WebSocket 연결
- URL을 가진 시험:
curl -I https://[YUANBAO_API_DOMAIN]
미디어 업로드 실패
** 원인**: COS 자격 증명은 유효하지 않거나 미디어 서버는 제한이 없습니다.
Fix:
- API DOMAIN를 검증하는 것은 정확합니다
- 미디어 업로드 권한이 봇에 사용할 수 있는지 확인하세요.
- 미디어 파일을 액세스하고 손상되지 않습니다.
- 플랫폼 관리자를 가진 COS 물통 윤곽을 검사하세요
집 수로에 전달되지 않는 메시지
** 원인**: 홈 채널 ID 형식은 잘못된 또는 cron 작업은 트리거되지 않습니다.
Fix:
- YUANBAO HOME CHANNEL는 정확한 체재에 있습니다
- 자동 탐지 정확한 체재에
/sethome명령을 가진 시험 /status를 가진 cron 일 계획을 검사하세요- Verify 봇은 대상 채팅에서 권한을 보냅니다.
# # # 빈번한 연결
** 원인**: WebSocket 연결은 불안정하거나 네트워크는 신뢰할 수 없습니다.
Fix:
- 오류 패턴 확인
- 연결 설정에서 heartbeat timeout 증가
- Yuanbao API에 안정되어 있는 네트워크 연결
- 동위 로깅을 가능하게 고려하세요:
HERMES_LOG_LEVEL=debug
접근 제한
Yuanbao는 DM과 그룹 대화를 모두 위한 정밀한 곡물 접근 제한을 지원합니다:
# DM policy: open (default) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2
# Group policy: open (default) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2
이들은 또한 config.yaml에서 놓일 수 있습니다:
모델 번호: ```yaml platforms: yuanbao: extra: dm_policy: allowlist dm_allow_from: "user1,user2" group_policy: open group_allow_from: ""
## 고급 구성
## 메시지 Chunking
Yuanbao는 최대 메시지 크기를 가지고 있습니다. Hermes는 Markdown-aware Splitting(respects code Fences, table, 단락 경계)와 큰 응답을 자동으로 펑크합니다.
### 연결 모수
뒤에 오는 연결 모수는 민감하는 과태를 가진 접합기로 건축됩니다:
| 매개 변수 | 기본 값 | 설명 |
|-----------|---------|-------|
| WebSocket connect timeout | 15초 | WS Handhake를 기다리는 시간 |
| Heartbeat interval | 30초 | 연결이 살아있을 수 있는 주파수 |
| 최대의 재연결 시도 | 100 | 최대의 재연결 시도 |
| 리커넥트 백오프 | 1s → 60s (예정) | 재연결 시도 사이의 대기 시간 |
| 대답 심박수 간격 | 2 초 | RUNNING 상태는 빈도를 보냅니다 |
| 시프트 아웃 | 30초 | 아웃바운드 WS 메시지 |
:::note[기사]
이 값은 현재 환경 변수를 통해 구성할 수 없습니다. 그들은 전형적인 Yuanbao 배포에 최적화.
주요 특징
## Verbose 로깅
연결 문제를 해결하기 위해 debug 로깅 활성화:
```bash
HERMES_LOG_LEVEL=debug hermes gateway
다른 기능과 통합
Cron 작업
Yuanbao에서 실행되는 일정 작업:
/cron "0 */4 * * *" Report system health
결과는 당신의 가정 수로에 배달됩니다.
배경 작업
대화를 차단하지 않고 긴 작업을 실행:
/background Analyze all files in the archive
크로스 플랫폼 메시지
CLI에서 Yuanbao로 메시지 보내기:
hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"