Yuki: 오픈 소스 자가 호스팅 AI 에이전트 (v3.8.4)

중국어(기본) · 영어

Yuki는 오픈 소스로, 자체 호스팅 가능한 소셜 AI Agent로, 디지털 생명이 실제 사교 환경에서 어떻게 지속적으로 존재할 수 있는지 탐구합니다. 현재 QQ 개인 채팅 및 그룹 채팅에서 작동하며, 사람들과의 경험을 기억하고, 도구를 사용하며, 여러 메시지에 걸쳐 작업을 수행하는 영속적인 작업 환경을 활용할 수 있습니다. 신원과 기억은 자체 데이터베이스에 저장되므로, 모델, QQ 계정 또는 게이트웨이를 변경해도 계속 사용할 수 있습니다.

현재 공식 버전은 3.8.4입니다. 이 버전에서는 가시적 발언이 주 Agent의 명시적인 send_message로 통일되었으며, 선택적 그룹 채팅 의미론적 관찰(semantic observation), SELF 자율 참여 및 자율 자동화 기능이 추가되었습니다. Yuki는 발언하거나, 분할하여 전송하거나, 침묵할 수 있습니다. 자율 참여는 기본적으로 비활성화되어 있으며, 실제 QQ 그룹 채팅에서의 장기적인 효과는 여전히 검증 중입니다. 작업 환경은 별도로 배포해야 합니다. 3.8.4 공식 패키지에는 관리 WebUI가 포함되어 있지 않습니다.

현재 개발 베이스라인은 3.9.0이며, 아직 출시되지 않았습니다. 소스 코드 변경 사항과 모든 병합된 PR(Pull Request)은 3.9.0 출시 설명 초안에서 확인할 수 있습니다. 업그레이드 준비는 3.9.0 업그레이드 초안을 참고하십시오. 공식 다운로드 경로는 여전히 상단의 3.8.4 Release를 이용해야 합니다.

기본 direct 빌드: 동일한 메인 Agent 루프와 고정된 전체 도구 선언을 유지하며, 미러지에는 Monty binding, worker 또는 launcher가 포함되어 있지 않습니다. Code Mode는 명시적으로 이미지를 선택하고 활성화해야 하는 선택적 모드로, 활성화하기 전에 대상 머신의 자원 여유 공간을 별도로 검증해야 합니다.

관리 WebUI 및 공유 실행 Runtime: 기록 스타일의 인터페이스에서 실제 채팅, 실행 궤적(execution trace), 도구 회신(tool receipt), 모델 사용량 및 작업 영역을 확인하고, 모델 연결과 작업 라우팅을 관리합니다. 채팅, SELF, 플러그인, 자동화 및 Work 지속 실행은 주 Agent를 공유하며, WebUI는 기본적으로 비활성화됩니다.

복구 가능한 장기 작업: Work는 원래 목표, 누적 예산, 프로토콜 체크포인트 및 전달 회신을 보존합니다. 컨텍스트는 실제 요청 용량에 따라 정리되며, 연구 자료는 필요할 때 읽어옵니다. 터미널 대기, 하위 작업 및 사용자 추가 요구 사항은 기존 작업에 연결됩니다. 재시작으로 인해 이미 확인된 효과가 다시 수행되지는 않습니다.

단순화된 기억 전략: 동일한 키(key)의 독립적인 사실들은 공존할 수 있으며, 수정과 삭제는 fact ID를 기준으로 합니다. 삭제 근거/강화 점수, 자동 승격 및 용량 확보 기능이 있습니다. 추출(Extraction), SELF 및 Dream은 각각 모델을 선택할 수 있어 부분 정리와 미결 결과를 허용합니다.

Agent의 필요 기반 자료 검색: 장기적인 사실들은 search_memory를 통해 필요에 따라 검색되며, 더 이상 매 라운드마다 자동으로 주입되지 않습니다. 현재, 인용, 과거 첨부 파일, 작업 영역 및 승인된 도구 이미지는 모두 원래 메인 모델의 네이티브 멀티모달 입력으로 처리됩니다.

네트워크 연결 및 실제 프로토콜 피드백: 새로 설치하면 기본적으로 모델 검색이 활성화되며, 명시적 비활성화와 연결 능력 경계가 유지됩니다. 어댑터는 본문에서 도구 호출을 생성하지 않으며, 은밀하게 유료 지속 실행을 추가하지 않습니다. 실제 오류 및 알려진 사용량은 보존되며, 이미 배포되었거나 알 수 없는 효과는 원래 회신을 기준으로 확인합니다.

답변 전 데이터베이스 대기 시간 감소: 과거 읽기, 컨텍스트 준비 및 폐기 가능한 진단 쓰기는 핵심 쓰기 트랜잭션에서 분리되었습니다. 백그라운드 유지는 인덱싱, 경계 페이지네이션(bounded pagination) 및 짧은 트랜잭션을 사용합니다. 실제 지연 시간은 여전히 모델 응답, 도구 요청 및 호스트 자원에 영향을 받습니다.

기존 MCP 제거: 연결, 도구 디렉토리, 관리 페이지, SDK 및 자동화 진입점이 모두 단종되었습니다. 일반적인 도구 결과, 미디어 및 회신은 계속 보존됩니다. Plugin API는 3.4로 승격되었고, 데이터베이스 헤드는 0104입니다. 이전 플러그인은 적응하고 재승인해야 합니다.

음성 출력 종료: Genie 합성, 음색/선호도, 도구 매개변수, SDK/관리 기능, Worker 및 배포 의존성이 모두 제거되었습니다. 수신/인용 ASR(자동 음성 인식), 과거 음성 및 원래 회신은 보존됩니다. 업그레이드 전에 이전 실행, 콜드 스탠바이 음성 사실 및 인용된 파일을 먼저 확인한 후 전용 테이블로 마이그레이션합니다. 텍스트를 자동으로 재전송하거나 수정하여 전송하지 않습니다.

위 내용은 현재 소스 코드의 변경 사항입니다. 각 Provider의 실제 API, 자연 채팅 지연 시간 및 장기 작업 효과는 각각의 인수 테스트 기록에 따라 확인해야 합니다. 선택적 Code Mode의 격리 검증은 프로덕션 용량이나 장기 메모리 인수를 의미하지 않습니다.

활성화하면 Yuki는 모든 세션에서 공유되는 Linux 작업 디렉토리를 갖게 되어 다운로드 파일, Git 프로젝트, 스크립트 및 종속성을 저장할 수 있습니다. 파일 도구와 터미널 작업은 같은 파일을 사용하며, 일반 작업 파일은 더 이상 24시간마다 만료되지 않습니다.

• Bash, Python, Node.js, Git 및 기본 컴파일 도구가 사전 설치되어 있으며, pip, npm을 지원하고, Manager가 관리하는 apt 설치 및 환경 체크포인트 기능을 갖추고 있습니다.
• 터미널은 대화형 입력, 증분 출력, 취소 및 백그라운드 실행을 지원합니다. 작업을 먼저 시작한 후 메시지를 계속 처리하고 나중에 결과를 확인할 수 있습니다.
• Bot 또는 Manager가 재시작할 때, 환경 프로세스는 계속 실행될 수 있습니다. 환경 자체가 재시작된 경우, 일반 작업은 중단으로 표시되고, 등록된 서비스는 전략에 따라 복구됩니다.
• 선택한 파일이 불변 스냅샷(immutable snapshot)으로 배포되면 QQ 전송 링크를 통해 전달되며, 이전 artifact_id와의 호환성을 유지합니다.

기본 홈 디렉토리 용량은 2 GiB, 컨테이너 메모리 상한선은 512 MiB이며, 최대 하나의 주요 실행 작업, 네 개의 터미널 세션 및 두 개의 내부 서비스를 가질 수 있습니다. 환경에는 브라우저나 데스크톱이 없으며, Bot 데이터베이스, QQ 자격 증명 또는 호스트 Docker 제어 인터페이스가 마운트되지 않습니다.

이는 개별 배포 가능한 선택적 기능이며, Linux 호스트, gVisor 및 Yuki Manager가 필요합니다. 일반 Bot 배포 패키지에는 자동으로 설치되지 않습니다. 구성, 리소스 제한 및 복구 방법은 영문 '영속 환경 설명(Persistent Environment)'을 참조하십시오.

장기 기억(Long-Term Memory)은 안정적인 사실, 선호도 및 의미 있는 경험을 저장하는 데 사용됩니다. 일반 자동 추출 기능은 메시지를 집계하며, 명시적으로 기억할 것을 요청하거나 수정/삭제를 지시할 때만 즉시 처리합니다. 메인 Agent는 언제 search_memory를 호출할지 스스로 판단하며, 매 라운드마다 자동으로 검색하거나 모든 장기 사실을 컨텍스트에 넣지 않습니다. 검색은 현재 주체의 가시 범위와 작업 예산의 제약을 받으며, 결과에는 잘림 또는 불완전한 상태가 명시됩니다. 동일한 키(key)가 유일한 슬롯이 아니며, 사실은 ID와 실제 증거에 따라 저장됩니다. 추출(Extraction), SELF 성찰 및 Dream 정리는 모델 구성에서 각각 연결할 수 있습니다. 긴 대화는 Rollup을 통해 기록을 압축하며, 원본 기록은 여전히 독립적인 조회 경로를 가집니다.

short_state는 전역적으로 공유되고 경계가 있으며 만료되는 단기 기록 영역으로, 세션 간 정보를 임시 저장하는 데 사용됩니다. 이는 장기 기억 및 영속 파일과 분리되어 있습니다. 그룹 채팅과 개인 채팅이 자동으로 하나의 완전한 채팅 기록으로 합쳐지지는 않습니다.

기억 읽기는 여전히 구체적인 경계가 있습니다: 과거의 공동 그룹 관계는 인물 구조화 사실을 열어줄 수 있으며, 여기에는 개인 채팅 출처의 사실이 포함될 수 있지만, 타인의 원본 개인 채팅이나 사적 증거는 열어주지 않습니다. 배포 전에 Memory의 범위와 권한을 읽어보십시오. 모델 추출 및 회상은 오류가 있을 수 있으므로 중요한 정보는 출처를 교차 확인해야 합니다.

이미지 및 비디오: 현재, 인용 및 과거 첨부 파일, 그리고 Agent가 선택한 작업 공간 또는 승인된 도구 이미지는 모두 원본 메인 모델의 네이티브 이미지 입력을 공유합니다. 과거 첨부 파일은 내부 이벤트 인덱스, 세션 및 캐시 만료 기간에 따라 검증됩니다. 이미지 기능이 부족할 경우 읽지 않았다고 명확히 보고하며, 모델을 암묵적으로 변경하거나 독립적인 Qwen 시각 요약 기능을 호출하지 않습니다. MP4/MOV 비디오는 FFmpeg를 통해 프레임 추출되어 동일한 메인 Agent로 들어오며, 오디오 트랙을 분석하지 않으며 모든 순간을 포괄한다고 보장하지도 않습니다. 백그라운드 감정 분류 및 플러그인의 명시적 시각 기능은 여전히 독립적인 시각 연결을 사용할 수 있습니다. 음성 수신: 개인 채팅, 응답 전략에 맞는 그룹 채팅 및 인용된 음성은 Qwen ASR로 전사되어 채팅 기록, 검색 및 Rollup으로 들어옵니다. 천문(Qwen) 연결을 재사용할 수 있으며 로컬 합성 서비스에 의존하지 않습니다. 음성 합성과 전송 기능은 단종되었습니다. 음성 인식 설명을 참조하십시오. 파일 읽기: 텍스트, 코드, CSV/JSON, PDF 텍스트, DOCX 및 XLSX의 경계가 있는 추출을 지원합니다. 스캔된 PDF는 OCR을 수행하지 않으며, 표 공식은 재계산되지 않고, 매크로나 첨부 파일의 코드는 읽는다고 해서 실행되지 않습니다. 동일한 세션 내에서 후속 질문 시 원본 첨부 파일을 인용할 필요가 없습니다. Yuki는 필요에 따라 24시간 임시 캐시를 읽습니다. 네트워크 연결: 새로 설치하고 네트워크 스위치를 설정하지 않은 경우 기본값은 WEB_MODE=native이며, 명시적으로 disabled로 계속 비활성화하면 기존 연결된 검색 선택이 변경되지 않습니다. 활성화한다고 해서 모든 모델이 검색을 지원하는 것은 아니며, 네이티브 검색은 연결 선언으로 실제 능력을 필요로 합니다. Gemini는 독립적인 검색 브리지를 명시적으로 사용할 수 있습니다. 외부 web_search는 백엔드 구성이 필요합니다. 외부 검색은 기본적으로 Tavily를 사용하며, WEB_MODE=tavily 또는 WEB_SEARCH_BACKEND=deepseek_anthropic을 설정하여 DeepSeek 검색 브리지를 사용할 수 있으며, Tavily 키는 선택적 실패 안전장치 용도로만 사용됩니다. DeepSeek 메인 Agent는 현재 네이티브 검색을 선언하지 않습니다. 프로토콜 및 구성 경계는 모델 공급업체 설명을 참조하십시오.

채팅, 플러그인 활성화, 자동화 및 작업 재개에는 통일된 메인 Agent와 고정된 완전한 도구 계약이 사용됩니다. 도구 구조는 배포 내에서 고정되어 유지되며, 실행 시 권한과 예산을 다시 확인합니다. 이는 요청 접두사 변화를 줄이지만, Provider의 캐시 적중률을 보장하지는 않습니다.

과거 샘플에서 Gemini가 자연 그룹 채팅 한 회신 라운드에 대해 세 번의 요청을 사용했으며, 입력 가중치 캐시 비율은 **90.55%**였습니다. DeepSeek Responses의 수동 누적 채팅 실험 9회 요청은 **95.11%**였고, 이 중 8회의 열 연결(hot continuation)이 **99.02%**였습니다. 날짜, 시나리오 및 측정 범위가 다르므로 현재 온라인 적중률이나 수정 전후 속도 비교로 사용할 수 없습니다. 전체 샘플과 다중 시나리오 결과는 3.9.0 캐시 통계를 참조하십시오.

기본 배포에는 다음이 필요합니다:

• Linux amd64, 또는 Linux 컨테이너를 실행하는 Windows Docker Desktop;
• Docker Engine 및 Docker Compose v2;
• 프로젝트 연결에 필요한 Chat Completions 또는 Responses 프로토콜을 지원하는 사용 가능한 모델 서비스 구성;
• SnowLuma QQ 게이트웨이 및 로그인 계정. Yuki는 더 이상 NapCat을 지원하지 않습니다. 기존 게이트웨이 추상화는 다른 구현에도 계속 사용할 수 있습니다.

3.8.4 릴리스에서 배포 패키지를 다운로드하여 압축 해제한 후, .env와 모델 구성을 수동으로 작성하거나 구성 마법사를 사용할 수도 있습니다.

개발 메인라인에는 Claude Messages, Gemini GenerateContent 및 일반적인 Chat 공급업체 방언이 추가되었습니다. 여러 공급업체를 작업에 따라 명시적으로 구성할 수 있으며, 능력과 복구 경계는 모델 프로토콜 설명 및 다중 공급업체 예시를 참조하십시오. 이는 기존 3.8.4 배포 패키지의 기능 선언이 아닙니다.

Linux:

curl -fLO https://github.com/YuanYeYouTao/Yuki/releases/download/v3.8.4/install.sh
chmod +x install.sh
./install.sh

Windows PowerShell:

Invoke-WebRequest -Uri https://github.com/YuanYeYouTao/Yuki/releases/download/v3.8.4/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .
install.ps1

도우미(向导)는 설정만 담당합니다. 빈 디렉터리에 배포 패키지를 다운로드하고 검증하며, 기존 배포의 Compose, 플러그인 및 데이터는 유지합니다. 확인 후 설정을 백업하고 작성합니다. 서비스 중단, 데이터베이스 마이그레이션, 서비스 시작 또는 게이트웨이 전환은 수행하지 않습니다.

현재 3.9.0 소스 코드의 모델 연결 정보는 webui-config/model_profiles.toml에 저장되어 있습니다.

반면, 3.8.4 정식 패키지는 패키지 경로를 따릅니다. 최신 소스로 업그레이드하고 기존 배포가 config/model_profiles.toml만 있는 경우, 먼저 모델 설정 경로를 검토하고 마이그레이션해야 합니다. 도우미는 현재 WebUI의 모델 연결을 자동으로 덮어쓰지 않습니다. 지정된 파일이 누락되면 시작 시 명확하게 실패합니다.

최초 배포는 설정 완료 후, 배포 디렉터리에서 다음 명령어를 실행합니다:

docker compose config --quiet
docker compose pull
docker compose run --rm --no-deps --entrypoint qq-ai-bot-cli bot init-db
...

QQ 로그인 및 선택한 플러그인의 초기화도 완료해야 합니다. 최초 배포와 구 버전에서 업그레이드하는 방법은 3.8.4 업그레이드 가이드를 참조하십시오. 기존 배포는 원래의 프로젝트 이름, Compose 오버라이드 파일 및 마운트된 설정을 유지해야 합니다.

정식 이미지는 ghcr.io/yuanyeyoutao/yuki-qqbot:3.8.4입니다. 이전 버전인 3.8.4의 TTS Worker 자산은 여전히 해당 구 버전에 속하며, 현재 소스 코드에는 적용되지 않습니다. 배포 패키지에는 SHA256SUMS가 제공됩니다. 개별 다운로드하는 환경 템플릿 첨부 파일 이름은 default.env.example이며, 압축 파일 내부에서는 여전히 .env.example입니다.

3.9.0 소스 코드는 Plugin API 3.4를 사용하며, 데이터베이스의 단일 head는 0104입니다. 3.8.4 정식 패키지의 head는 0072입니다. 업그레이드는 여전히 실제 이미지와 패키지에 따른 마이그레이션을 따르며, 애플리케이션 버전 번호가 데이터베이스 검사를 대체할 수 없으며 stamp로 마이그레이션을 건너뛸 수 없습니다. 플러그인은 MCP 의존성을 제거하고 API 3.4에 맞게 조정한 후 재승인해야 합니다. 이전의 llm.generate / agent.run은 주 진입점으로 통합되었습니다.

3.9.0 개발 커밋을 사용하기 전에, 먼저 업그레이드 초안에 따라 기존 MCP 마운트, 환경 설정 및 관리 권한을 검토해야 합니다. 퇴역된 관리 승인은 엄격한 검증 통과를 막습니다. 데이터베이스가 새 head로 제출된 후에는 이전 이미지만으로 되돌릴 수 없으며, 이전 백업으로 업그레이드된 메시지나 회신을 덮어쓸 수도 없습니다.

업그레이드 전에 일관된 데이터베이스, 설정, 플러그인 및 파일 백업을 저장하십시오. 영구 환경의 경우 홈 디렉터리와 실행 기록도 저장해야 합니다. 쓰기 중단은 Bot과 관련 Manager에만 해당하며, 전체 Docker 또는 QQ 게이트웨이를 종료할 필요는 없습니다. 롤백 시에는 업그레이드된 새 메시지, 파일 및 회신을 먼저 보존해야 합니다. 현재 소스 코드는 3.9.0 업그레이드 초안을 참조하십시오.

docker compose ps
docker compose logs --tail 200 bot
docker compose exec bot qq-ai-bot-cli gateway doctor --provider snowluma

모든 명령어는 배포 시 사용된 Compose 매개변수를 그대로 사용합니다. 하나의 QQ에는 활성 연결이 하나만 허용되며, 중복 연결은 이전 연결을 밀어내지 않습니다. 기존 배포의 Compose와 .env 파일은 설치 프로그램에 의해 자동으로 대체되지 않으며, 퇴역 설정 처리는 SnowLuma 배포 및 업그레이드 초안을 참조하십시오.

Alice는 AI가 실제 채팅에 지속적으로 참여하는 방법을 탐구하고; Letta는 기억을 가지고 상태를 유지할 수 있는 Agent에 중점을 두며; AstrBot은 QQ와 같은 채팅 플랫폼용 Agent 및 플러그인 프레임워크를 제공합니다. Yuki는 이러한 능력들이 어떻게 단일하게 존재하는 그룹 채팅 주체 내에서 협력적으로 작동하는지에 초점을 맞춥니다: 사람을 인식하고, 공동의 경험과 기억을 축적하며, 언제 참여할지 자율적으로 판단합니다.

개발 전에 '공동 아키텍처 제약' 및 '아키텍처 문서 인덱스'를 읽으십시오. 과거 작업서는 현행 계약을 대체하지 않습니다.

하나의 데이터베이스는 하나의 장기 지속되는 Yuki에 해당합니다. 인물, 그룹 공간, QQ 계정 및 게이트웨이 연결은 각각 모델링되며, 채팅 기록과 기억은 특정 로그인 연결에 묶이지 않습니다. 도구는 백엔드 실행 권한, 예산, Idempotency(멱등성) 및 감사 검사를 통해 관리됩니다.

현재 QQ 상호작용, CLI 및 공유 Control Plane을 제공합니다. 현재 소스코드의 수첩 관리 WebUI는 기본적으로 비활성화된 HTTP 관리를 통해 채팅, 실행 추적(execution trace), 설정 및 자동화 등의 서비스에 연결됩니다. 3.8.4 정식 배포판에는 이 관리 인터페이스가 포함되어 있지 않습니다. 빌드, 권한 및 기능 경계는 WebUI 문서를 참조하십시오.

uv sync --extra dev
uv run ruff format --check
uv run ruff check
...

개발 시 변경 범위에 따라 방향성 검증을 수행합니다. Quality 단계에서는 소스코드 검사, 프론트엔드 테스트/빌드 및 회귀 방지(regression)를 유지합니다. Release 단계에서는 버전 식별, 단일 직접 이미지(direct image), 그리고 소스코드 없는 배포 패키지를 검증하며, 더 이상 이전 Memory 품질 게이트나 중복 배포 체인을 실행하지 않습니다. 상주 회귀 테스트는 가짜 Provider와 격리된 데이터베이스를 사용합니다. Gemini, DeepSeek 등 유료 API의 캐시 비교는 별도로 수동으로 실행하며, 보고서는 콜드 라운(cold run), 핫 라운(hot run) 및 누락 측정치를 구분하고 일반 테스트나 고정 히트율 임계값으로 간주하지 않습니다.