一、 前言

  在上一篇文章 中，我们已经成功在 Hexo (Butterfly主题) 框架下部署了 Cubism 3.0+ 标准的 Live2D (.moc3) 模型。但交互性却略显不足。在这个大模型时代，为什么不给博客看板娘装上一个真正的大脑呢？
  本文将作为上一篇教程的进阶，将介绍 Live2D AI 聊天功能的前端架构设计与后端部署教程。为了相关信息完整性，请务必先浏览上一篇文章内容。

本项目的 AI 聊天功能是基于 Deepseek + FastAPI 后端服务实现的，在开始后端部署前请确保你已经具备一个可用的云服务器以及一个可用的deepseek API 密钥。

二、 前端架构说明

  为了不破坏原有 Live2D 渲染框架，由 waifu-chat.js 负责对话逻辑，waifu-tips.js 仅作为AI对话功能的触发入口。下面展示了前端从触发唤醒到完成一次 AI 对话的交互流程：

2.1 侧边栏工具

  在waifu-tips.js的工具栏配置对象 U 中，新增一个 chat 工具，并为其绑定回调函数。这里通过全局变量 window.live2dChatInstance 来进行跨文件通信：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// waifu-tips.js
var U = {
    chat: {
        icon: '<svg>...</svg>',
        callback: () => {
            if (window.live2dChatInstance) {
                window.live2dChatInstance.toggle();
            } else {
                window.waifuShowMessage("聊天模块未加载", 3000, 10);
            }
        }
    },
    // 其他原生工具 (hitokoto, photo, etc.)
}

2.2 聊天引擎

  waifu-chat.js定义整个 AI 交互的逻辑，并通过 Live2DChat 类进行封装：

  • 前端 RAG 机制
      调用 getCurrentPageContext() 抓取 hexo 博客容器#article-container 里的纯文本，并通过读取 Hexo 的 /search.xml 建立 blogIndex 进行全局匹配。让 AI 能够精准回答“这篇文章讲了什么”或“你的博客里有没有关于 XX 的内容”。
  • 打字机与 Markdown 渲染
      拦截后端的完整返回，并添加“打字”动画效果和“等待”动画效果。同时引入 marked.js 对 AI 返回的 Markdown 进行解析，正则处理可能导致的 DOM 解析错误问题。
  • 聊天边界管理
      聊天框弹出时，利用 getBoundingClientRect 与视窗大小计算，确保不管看板娘被拖拽到页面的哪个角落，聊天窗口永远不会超出屏幕边界被遮挡。

2.3 自定义配置

  将 System Prompt、欢迎语、快捷选项和 RAG 截断策略写入waifu-chat.json。这样以后修改 AI 人设或欢迎语时，无需动前端核心代码，直接修改配置文件即可。

三、后端配置

3.1 后端程序设置

  后端程序主要负责接收前端请求，调用 DeepSeek API 获取 AI 回答，并返回给前端。使用 FastAPI 框架来实现此功能。
  在云服务器上创建自定义的工作目录：

1
2
3
4
mkdir /home/git/live2dChat
cd /home/git/live2dChat
touch main.py
vi main.py

  向 main.py 中写入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
import os
from fastapi import FastAPI, Request, HTTPException
from fastapi.middleware.cors import CORSMiddleware
import httpx

app = FastAPI()

# CORS 白名单，保护前端请求
ALLOWED_ORIGINS = [
    "https://你的域名", # 这里请务必替换为你博客的实际域名
    "http://localhost:4000"
]
app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,
    allow_credentials=True,
    allow_methods=["POST", "OPTIONS"],
    allow_headers=["*"],
)

# 环境变量读取
DEEPSEEK_API_KEY = os.getenv("DEEPSEEK_API_KEY")
# API 接口为 /api/chat
@app.post("/api/chat")
async def chat_proxy(request: Request):
    try:
        data = await request.json()
        messages = data.get("messages", [])
        
        payload = {
            "model": "deepseek-chat",
            "messages": messages,
            "stream": False
        }
        
        headers = {
            "Authorization": f"Bearer {DEEPSEEK_API_KEY}",
            "Content-Type": "application/json"
        }
        
        # 异步调用模型 API
        async with httpx.AsyncClient() as client:
            response = await client.post(
                "https://api.deepseek.com/chat/completions",
                json=payload,
                headers=headers,
                timeout=30.0
            )
            response.raise_for_status()
            return response.json()
            
    except httpx.HTTPError as e:
        raise HTTPException(status_code=502, detail=f"Upstream Error: {str(e)}")

  安装python依赖：

1
pip install fastapi httpx uvicorn

3.2 配置 Systemd 守护进程

  建立环境变量文件并写入 DeepSeek API Key：

1
2
echo 'DEEPSEEK_API_KEY="这里为 DeepSeek API密钥"' > /home/git/live2dChat/.env
chmod 600 /home/git/live2dChat/.env

  创建 /etc/systemd/system/live2dchat.service 文件，并写入以下内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
[Unit]
Description=Live2D Chat FastAPI Proxy Service
After=network.target

[Service]
User=root
WorkingDirectory=/home/git/live2dChat
EnvironmentFile=/home/git/live2dChat/.env
ExecStart=/usr/bin/python3 -m uvicorn main:app --host 127.0.0.1 --port 8555
Restart=always
RestartSec=3

[Install]
WantedBy=multi-user.target

  程序的服务端口为 8555，当然你也可以根据需要修改为其他端口，但请确保后续 Nginx 反向代理配置中的端口一致。然后启动并验证服务是否正在运行：

1
2
3
systemctl daemon-reload
systemctl enable live2dchat.service
systemctl status live2dchat.service

  检查 /home/git/live2dChat/.env 文件中是否正确存入了 DEEPSEEK_API_KEY：

1
DEEPSEEK_API_KEY="DeepSeek API密钥"

3.3 Nginx 反向代理

  在 /etc/nginx/nginx.conf 中配置 IP 请求限制：

1
2
3
4
http {
    # 其他配置...
    limit_req_zone $binary_remote_addr zone=live2d_api_limit:10m rate=10r/m; # 每分钟限制 10 次请求
}

  然后在 /etc/nginx/sites-available/default 或你的 Nginx 配置文件中添加以下 location 块，将 /api/chat 的请求反向代理到 FastAPI 服务：

1
2
3
4
5
6
7
8
9
10
11
server {
    # 其他 server 配置...
    location /api/chat {
        limit_req zone=live2d_api_limit burst=10 nodelay;
        proxy_pass http://127.0.0.1:8555;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

  重载Nginx配置：

1
2
sudo nginx -t
sudo systemctl reload nginx

  到这里后端服务就部署完成了。

四、前端部署

  前端代码的开源地址为：LuoTian001/live2d-widget-AIChat。如果觉得教程对你有帮助，烦请 star 支持一下！( •̀ ω •́ )✧

4.1 文件说明

  项目采用模块化设计，分离基础渲染层与 AI 逻辑层。主要目录结构与各文件功能说明如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
live2d-widget-AIChat/
├── Core/                      # 基础渲染与交互层
│   ├── live2dcubismcore.js    # Live2D Cubism 官方核心 Web 库
│   ├── live2d-sdk.js          # Live2D 渲染与控制 SDK
│   ├── waifu-tips.js          # 看板娘主控制逻辑脚本
│   └── waifu.css              # 看板娘本体基础 UI 样式表
├── chatCore/                  # AI 聊天逻辑层
│   ├── waifu-chat.js          # AI 聊天核心脚本
│   └── waifu-chat.css         # AI 聊天窗口样式表
├── config/                    # 进阶配置文件目录
│   ├── model_list.json        # 模型列表与加载提示语配置
│   ├── waifu-chat.json        # AI 对话模块配置
│   └── waifu-tips.json        # 看板娘基础交互语料库
├── model/                     # moc3 模型资源存放目录
├── live2d.js                  # 项目前端总入口脚本
└── live2d.json                # 基础全局配置文件

4.2 前端部署

1
2
cd 你的博客目录/source/
git clone git@github.com:LuoTian001/live2d-widget-AIChat.git live2d

  在_config.yml博客配置文件下添加以下代码，排除hexo对 live2d 目录的渲染：

1
2
skip_render: 
  - 'live2d/**'

  在 _config.butterfly.yml 文件中，找到 inject.bottom 节点，加入以下代码：

1
2
3
inject:
  bottom:
    - <script src="/live2d/live2d.js" defer></script>

  同时确保你已经安装 hexo-generator-search 插件，并在 _config.butterfly.yml 中正确配置了 search.path。这是 AI RAG 检索功能的依赖：

1
2
cd 你的博客目录/
npm install hexo-generator-search --save
1
2
3
4
5
6
7
8
9
10
search:
  use: local_search
  path: search.xml
  field: post
  content: false
  format: striptags
  limit: 1000

local_search:
  enable: true

  重新部署hexo clean && hexo g && hexo d，访问博客后你应该能够看到看板娘已经成功加载，并且侧边工具栏中出现了新的“Chat”图标。点击它就可以打开 AI 聊天窗口了。

五、参数配置

  live2d.json：负责全局路径控制与基础挂件行为定义。

参数 说明
base.cdnPath 外部资源的 CDN 加速路径指向地址，默认为本仓库main分支
base.localPath 本地资源路径的相对或绝对地址，如果你按照前述教程进行了部署，则地址为/live2d/
base.homePath 博客首页的路由地址，默认为 /
tools 侧边工具栏启用的功能按钮标识数组
chat：核心交互工具，点击唤醒 AI 聊天窗口界面。
hitokoto：点击后看板娘将请求并展示一条随机的一言文本或毒鸡汤。
express：点击随机切换当前模型内置的特殊表情集。
info：点击跳转至博客默认的关于页面或站长信息页。
quit：点击后彻底隐藏并关闭看板娘挂件。
drag.enable 是否开启看板娘拖拽功能，默认false
drag.direction 允许拖拽的方向数组，["x", "y"]表示允许 x 方向和 y 方向拖拽
switchType 模型与材质的切换触发规则，默认为order顺序切换
chat.apiUrl 后端 AI 对话接口的默认请求路由地址，需替换为https://你的博客域名/api/chat

六、进阶配置

  /config：包含更详细的语料、模型列表与 AI 逻辑设置。

config/waifu-chat.json (AI 对话配置)

参数 说明
api.url 后端 AI 对话接口的请求路由，默认/api/chat
ui.title 聊天窗口顶部栏显示的标题文本
ui.placeholder 底部消息输入框的占位引导提示文本
ui.errorMsg 后端接口响应异常或网络阻断时的原生错误提示语
ui.typingSpeed 模拟打字机动画的单字符输出延迟时间毫秒值，数值越大打字越慢，默认为25
chat.includeCodeBlocks 是否向 AI 提交文章中的代码块，关闭可节省 token，默认为false
chat.storageKey 浏览器 LocalStorage 持久化存储对话历史记录的键名
chat.maxHistory 存储在本地的最大历史对话消息对象数量限制，默认为20
chat.pageContextMaxLength RAG 核心配置： 抓取页面正文的最大字符截断长度，数值越高 RAG 检索越全面，但务必注意 deepseek 的单次请求 token 上限以及 token 消耗情况，默认为3000
chat.pageContextSelector RAG 核心配置： 当前页面阅读器抓取的 DOM 目标选择器，默认为#article-container，如果你的博客未采用 Butterfly 主题或更改了文章容器的 ID/Class，请务必同步修改此字段
chat.searchXmlPath Hexo 全站索引文件路径用于全局知识库匹配，默认为/search.xml
chat.welcomeMsg 访客首次打开聊天框时 AI 主动发送的第一条破冰消息
chat.welcomeOptions 预设快捷按钮数组包含显示文本与实际发送指令
display：按钮在界面上显示的文本内容
send：按钮实际发送给 AI 的指令内容，可设置多条 send 内容，会随机抽取一条发送
chat.systemPrompt 系统人设与输出约束提示词数组，如果需要分行显示，每条指令请用,隔开
chat.contextTemplate RAG 隐式上下文拼装模板对象规范化拼接格式，基本无需修改
truncateMsg：用于提示用户文章太长已产生截断

config/waifu-tips.json (基础交互语料配置)

参数 说明
mouseover 鼠标悬停在特定 DOM 元素上时触发的提示语配置
selector：指定触发提示语的 DOM 元素选择器，可以自定义 DOM 元素以触发不同交互
text：显示的提示语信息
click 鼠标点击特定 DOM 元素时触发的提示语配置
seasons 根据特定日期或节日触发的季节性提示语配置
time 根据当前时间段触发的日常问候提示语配置
message 包含控制台打开与文本复制等特殊事件的默认提示语

config/model_list.json (模型加载配置)

参数 说明
models 可用 Live2D 模型的目录名称数组
messages 对应模型加载完毕后显示的专属提示语数组

七、注意事项

  • AI 模块的低耦合说明
      AI 对话引擎被完整抽离在 chatCore 目录下，如果你不想开启 AI 功能，只需在live2d.json中将 tools.chat 删除即可，看板娘依然可以作为普通的 Live2D 挂件正常运行。
  • 基础功能配置简化说明
      本项目在原有框架上对 Live2D 功能进行了一定程度的默认简化。如果你需要进一步自定义模型，例如自定义 .exp3.json 触发专属表情、为 .motion3.json 动作绑定口型与音频、或调整模型在 Canvas 画布中的 scale 缩放与 translate 坐标偏移量等，请务必参阅原项目的详细文档 👉 live2d-widget-v3 使用说明。
  • RAG 容器匹配说明
      waifu-chat.js 中的本地阅读器默认通过 #article-container 选择器来提取当前页面的正文文本。如果你的 Hexo 博客未采用 Butterfly 主题，或者你在主题魔改中更改了文章主容器的 ID/Class，请务必在 /config/waifu-chat.json 中同步修改 pageContextSelector 字段。同时需检查你的站点根目录是否存在 search.xml 文件（由 hexo-generator-search 生成），并将其路径正确配置到 searchXmlPath 字段。

八、移动端适配

  由于 Live2D 模型的交互特性和屏幕尺寸限制，本项目在移动端是禁用的。如果想在桌面端使用本项目且在移动端提供 AI 聊天功能，可结合我的另一个项目：hexo-AIChat-Plugin。以下是双端配置教程：

  1. 部署 Live2D Widget with AI Chat
    按照前述教程部署本项目，确保桌面端能够正常显示看板娘和 AI 聊天功能。
  2. 部署 hexo-AIChat-Plugin
    在同一博客中部署 hexo-AIChat-Plugin 项目，并确保桌面端和移动端都能正常访问 AI 聊天功能。为了严格验证有效性，建议在 bottom 中分别注入两个项目的入口脚本并进行测试。
  3. 配置双端注入脚本
    在 博客根目录/source/js/ 下创建 ai-manager.js，并添加以下内容：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
(function() {
    function detectMobile() {
        const userAgentMatch = /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent);
        const screenWidthMatch = window.innerWidth <= 768;
        return userAgentMatch || screenWidthMatch;
    }
    // 动态创建 script
    const script = document.createElement('script');
    script.defer = true;

    if (detectMobile()) {
        // 移动端：加载 aichat-plugin.js
        script.src = '/aichat/aichat-plugin.js';
        console.log('[AI Manager] 检测到移动端，正在加载悬浮球 AI 助手...');
    } else {
        // 桌面端：加载 live2d.js
        script.src = '/live2d/live2d.js';
        console.log('[AI Manager] 检测到桌面端，正在加载 Live2D 看板娘...');
    }
    document.body.appendChild(script);
})();

  在_config.yml中排除 hexo 对 js 目录的渲染：

1
2
skip_render: 
  - 'js/**'

  在 inject.bottom 节点加入以下代码，注意这里无需再引入 live2d.js 和 aichat-plugin.js：

1
2
3
inject:
  bottom:
    - <script src="/js/ai-manager.js"></script>

  重新部署博客后，桌面端将显示 Live2D 看板娘和 AI 聊天功能，而移动端将显示悬浮球 AI 助手，实现双端适配。