Afterglow

简体中文

English
English

简体中文

English
English

外观

快速开始 ​

TIP

开发者备注：我个人非常推荐源码部署，这方便调整配置，并且高级功能以及试验功能在源码部署的情况下将非常方便配置以及使用。

环境要求 ​

工具要求用途
Python3.12.x（>=3.12,<3.13）后端运行时
uv当前稳定版Python 依赖管理
Node.js20 或更高仅构建前端时需要
pnpm当前稳定版仅主聊天前端需要

Afterglow 不内置模型。至少需要一个 OpenAI 兼容聊天模型和一个 Embedding 服务。 聊天记录可来自 QQChatExporter、WeFlow、Douyin Chat Export 或 Afterglow Chat 中间格式，详见 导入聊天记录。

推荐：使用配置向导 ​

首次启动不需要提前创建 .env：

bash
cd backend
uv sync --extra dev
XUWEN_LANGUAGE=zh-CN uv run uvicorn xuwen.chat_api.app:create_app --factory --reload

缺少关键配置时，终端会输出配置地址和一次性 token。打开 http://127.0.0.1:8000/config/，输入 token 后完成以下步骤：

  1. 从一个或多个聊天文件识别双方身份。
  2. 选择关系、persona 模板和后端语言。
  3. 配置并测试主聊天模型。
  4. 配置并测试 Embedding，可选启用打标。
  5. 选择生活时间线、视觉理解、联网搜索和互动决策等可选能力。
  6. 配置 Query Rewrite 与 Cross-encoder Reranker。
  7. 导入聊天记录并生成 persona、风格与作息画像。
  8. 设置后端访问密码 XUWEN_API_KEY。

向导会写入 backend/.env，旧文件备份到 .env-backups/。完成后停止并重新启动后端， 配置向导会自动关闭。

页面首次访问根据浏览器语言选择：简体或繁体中文自动中文，其他语言英文；下拉框可手动切换并保存。服务商预设仅中文显示；英文对空白服务填充 Google Gemini 聊天、OpenAI 向量和辅助模型，保护已有配置与输入，密钥由用户填写。

语言设置

本页的启动和 CLI 示例显式指定中文；英文页面的示例显式指定英文。文档或前端的语言下拉框只切换界面，不会修改后端语言。

设置中文 / 英文作用
后端 .envXUWEN_LANGUAGE=zh-CN / XUWEN_LANGUAGE=en启动提示、默认输出与主动消息；未设置时默认英文，修改后完全重启
CLI 参数--language zh-CN / --language en覆盖本次命令的提示和支持的生成内容；不写回 .env
HTTP 请求头Accept-Language: zh-CN / Accept-Language: en覆盖本次请求的提示和分析生成语言；主动消息仍由后端配置决定

CLI 优先级是 --language → 进程环境变量 XUWEN_LANGUAGE → 选定 .env 的 XUWEN_LANGUAGE → 默认 en。启动命令前的 XUWEN_LANGUAGE=zh-CN 是 Bash / Linux / macOS / WSL 写法，只影响该进程并覆盖 .env；不是 Uvicorn 的命令行参数。要长期使用中文，在 backend/.env 保存 XUWEN_LANGUAGE=zh-CN，以后可省略命令前缀。

Windows PowerShell 在 backend/ 目录中这样启动：

powershell
$env:XUWEN_LANGUAGE = "zh-CN"
uv run uvicorn xuwen.chat_api.app:create_app --factory --reload

CLI 的 --language 在 Bash 和 PowerShell 中写法相同，可放在子命令前或后：

bash
uv run xuwen --language zh-CN --help
uv run xuwen stats --language zh-CN

HTTP 提示及分析生成输出按 Accept-Language 选择，无支持项时回退后端配置。普通聊天尊重明确语言要求及当前对话，旧原文、自定义提示词不会自动翻译。

只需要修改配置时，可启动轻量入口：

bash
cd backend
uv run python -m xuwen.web_ui --language zh-CN

浏览器访问 http://127.0.0.1:8765/config/，使用该进程打印的 token。独立入口也支持 --language en|zh-CN。

手动配置 ​

bash
cd backend
uv sync --extra dev
cp .env.example.zh-CN .env

在 .env 中将 XUWEN_LANGUAGE=en 改为 XUWEN_LANGUAGE=zh-CN，并填写身份、聊天模型、Embedding 和 API 密钥。中文注释模板的默认值仍为英文，注释语言不决定运行语言。字段说明见配置参考。 然后导入历史聊天：

bash
uv run python -m xuwen.ingestion.cli import 路径/到/聊天记录.json --language zh-CN
uv run python scripts/analyze_persona.py 路径/到/聊天记录.json
XUWEN_LANGUAGE=zh-CN uv run uvicorn xuwen.chat_api.app:create_app --factory --reload

scripts/analyze_persona.py 和 scripts/check_proactive_quality.py 是独立辅助脚本，目前没有 --language 参数，部分控制台提示仍为中文。不要给它们追加该参数；需要选择语言的导入或分析任务请使用主 CLI 的 --language zh-CN / --language en。

多文件、JSONL、微信、图片和 persona 合并说明见导入聊天记录。

启动前端（可选） ​

主聊天前端用于本地聊天、记忆溯源和调试：

bash
cd frontend
pnpm install
pnpm dev

打开 http://127.0.0.1:5173/。只使用后端 API 时不需要安装前端依赖。

接入 OpenAI 兼容客户端 ​

Afterglow 提供 Chat Completions 与 Responses API。最小请求：

bash
curl -H "Accept-Language: zh-CN" -X POST http://127.0.0.1:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <XUWEN_API_KEY>" \
  -d '{
    "messages": [{"role": "user", "content": "在吗"}],
    "conversation_id": "my-conv-1"
  }'

客户端传入的 model 只是兼容字段，实际模型由 .env 的 CHAT_MODEL 决定。完整协议见 后端 API。

Docker ​

不希望安装 Python 和 uv 时，使用Docker 部署。源码与容器可以共享同一份 .env 和 .data/，但不要同时启动以免端口冲突。

健康检查 ​

bash
curl http://127.0.0.1:8000/healthz
curl -H "Accept-Language: zh-CN" -H "Authorization: Bearer <XUWEN_API_KEY>" \
  http://127.0.0.1:8000/readyz

/healthz 是唯一默认免鉴权的业务 API 端点；配置向导使用独立会话 token。

AGPL-3.0-or-later

Afterglow