“Can I get a kisssunset”——这句话如果出现在《小马宝莉》同人社区里往往不是一声简单的告白而是一种创作驱动粉丝想让余晖烁烁Sunset Shimmer真的看见自己、回应自己。传统同人创作里角色是被写出来的你发一张图、写一段文小马不会回头看你一眼。但从技术开发的视角看这句话其实是一个非常好的起点如果你想让余晖烁烁真的“开口”和你聊天当前的开发工具链完全支持低成本实现。这篇文章不是讲同人创作而是以“余晖烁烁”这个角色为例讲清楚如何把一类角色向粉丝应用从想法变成可运行的程序用角色卡Character Card定义人格用对话模型接口实现聊天用语音合成TTS让它说话再用前端页面把它们串成一个能点开就聊的网页应用。看完这篇文章你能跑通一个本地可运行的角色互动 demo也能判断这类应用在真实项目中该怎么设计、该避开哪些坑。1. 这篇文章真正要解决的问题先泼一盆冷水很多第一次做“角色 AI”的开发者以为难点在模型本身于是花大量时间折腾微调、RAG、向量数据库。实际做下来你会发现对单角色互动应用来说微调和 RAG 都是可选项真正的难点在另外四件事第一角色的“人格”如何稳定复现。同一个余晖烁烁在不同轮对话里不能说两句就变成一个完全陌生的角色。这个问题靠提示词工程和角色卡规范就能解决不需要训练模型。第二对话接口怎么接。你需要一个能返回文本的模型服务它可以是本地部署的开源模型也可以是云端的合规服务。关键是接口格式要统一最通用的是 OpenAI 兼容格式。第三角色能不能开口说话。文本聊天已经不够沉浸用户希望角色有声音。这里需要接入 TTS 服务并把语音文件返回给前端播放。第四前端怎么呈现。一个能聊天的网页或者小程序需要把用户输入、模型回复、语音播放三件事串起来。这部分如果不提前设计很容易在联调时手忙脚乱。文章核心判断角色互动应用的本质不是“训练一个角色模型”而是“用工程手段把模型、语音和人机交互接口组合成一个符合角色设定的体验产品”。因此这篇文章适合三类读者想做粉丝向角色应用、IP 互动应用的独立开发者。想学习 Agent 对话架构、但对“角色人格”部分比较陌生的后端开发者。希望把大模型能力落地成可演示产品的产品经理或全栈工程师。读完你会得到一套完整的角色应用开发思路、可复制的代码示例、一份常见问题排查清单以及关于合规和内容安全的工程建议。2. 核心概念角色互动的四个技术支柱角色互动应用听起来很抽象拆开就四块角色人格、对话服务、语音输出、页面容器。每块都能用现有工具解决不需要从零发明。2.1 角色人格角色卡Character Card角色卡是给模型看的“剧本”用结构化文本描述角色是谁、性格如何、说话风格怎样、有哪些不能做的禁忌。它本质上是一段精心设计的 System Prompt只不过以标准化格式保存方便复用和分发。一个角色卡通常包含角色名、身份背景。性格特征与说话风格。与用户的关系设定。禁止行为列表。若干示例对话。为什么角色卡重要因为大模型默认是“百科全知助手”风格你问它太阳系有几颗行星它列数据你让它扮演角色它容易演成“AI 扮演的角色”。要让它稳定就必须把角色设定写得极其具体不给模型“滑回助手模式”的空间。2.2 对话服务Chat Completion 接口对话模型的核心接口范式是“多轮消息”。你把用户消息、历史记录、角色卡拼接成消息列表模型返回一条回复。这个范式如今已经是行业标准绝大多数模型服务都提供 OpenAI 兼容的 HTTP 接口。一个最简对话请求的 JSON 结构{ model: your-chat-model, messages: [ {role: system, content: 你是余晖烁烁}, {role: user, content: 你好今天心情怎么样} ] }模型服务的选型影响成本、私密性和效果。如果是个人玩可以用本地开源模型保证数据不出机器如果是做公开产品要选有内容审核能力的云服务。文章后面的示例按“兼容 OpenAI 格式”来写这样不管后端接什么服务代码都不用改。2.3 语音合成TTS 让角色开口TTS 的角色是“把文本变成声音”。到 2025 年高质量的 TTS 已经不那么昂贵甚至有一些免费或低成本的方案能满足 demo 需求。但真实产品落地时建议选有商业授权、音色稳定、支持多情感控制的正式服务。从工程角度你需要的是一个“文本进音频文件或音频流出”的接口。音频可以保存为 mp3 或 wav然后交给前端播放。如果你的页面要支持按一下说话、再按一下停止前端还需要处理音频播放状态。2.4 页面容器前端交互层页面容器的任务是把用户输入发给后端、拿到回复后展示文字并播放语音。这个词听起来大实际可以是一个单页 HTML 文件。对原型和 demo 来说后端提供 API前端负责交互两者用 HTTP 通信是最简单可靠的架构。3. 整体架构与技术选型基于上面四个支柱一个适合个人开发和中小型产品的单角色互动应用架构可以这样设计前端一个 HTML 页面负责聊天展示、输入、语音播放。后端一个 Python 服务负责接收前端请求、调用模型接口、调用 TTS、返回结构化响应。模型服务独立部署的本地开源模型或云端兼容 OpenAI 格式的服务。TTS 服务可选本地或云端返回音频 URL前端拿到后直接播放。架构关系很简单用户浏览器 - 前端页面(AJAX) - Python后端 - 模型对话服务 - TTS服务 - 返回音频URL为什么用 Python 后端而不是 Node对这个项目Python 生态对大模型和 TTS 的封装更成熟写起来最快。FastAPI 自带接口文档联调时很方便。前端则用原生 HTML JavaScript不引入打包器减少环境依赖方便读者把代码粘到本地就能跑。选型原则对话模型优先选支持多轮对话和系统提示词的开源模型量化后的 7B~14B 模型在个人电脑上也能跑出不错效果。TTSdemo 阶段优先简单方案正式产品换成商业服务。前端原生三件套不引入复杂框架避免学习成本。4. 环境准备与前置条件开始前需要准备以下环境。版本以当前实际安装为准本文重点演示通用思路不写死版本号。操作系统Windows / macOS / Linux 均可。Python3.10 或更高版本。包管理工具pip 或 uv。模型服务本地部署的开源模型或任意提供 OpenAI 兼容接口的云端服务。Node.js不是必需但如果后面想用 npm 做静态托管可以先装。建议创建独立的 Python 虚拟环境避免依赖冲突python3 -m venv venv source venv/bin/activate # Windows 上使用 venv\Scripts\activate然后安装依赖pip install fastapi uvicorn openai pydantic requests edge-tts如果你选择支持 OpenAI 兼容接口的模型服务需要在本地启动它。以常见开源模型服务框架为例先启动模型服务python -m vllm.entrypoints.openai.api_server \ --model your-model-path \ --served-model-name sunset-model \ --port 8001如果本地显存不足更简单的方式是连接云端服务地址。需要说明的是这里的代码通过 base_url 指定服务地址所以无论本地还是云端后端代码都无需改动。注意一点如果你的模型服务启动在 8001 端口后端 FastAPI 启动在 8000 端口前端页面的请求必须指向 FastAPI而不是直接指向模型服务。这样做的原因是前端只和你的后端通信后端统一转发到模型服务和 TTS便于做参数控制、内容审核和日志记录。5. 后端实现角色卡与对话接口后端是整个应用的核心它承担三件事加载角色卡、调用模型对话接口、调用 TTS 返回语音。5.1 设计角色卡 Prompt角色卡不只是一个名字而是一段完整指令。以余晖烁烁为例我设计了一个最小角色卡重点在于“说话风格”和“禁止项”这是让角色不跑偏的关键。你是余晖烁烁Sunset Shimmer来自《小马宝莉》系列的独特角色 你坚强、聪明、有点小骄傲但内心温暖重视朋友。 现在你正以人类学校的身份和一位新朋友聊天。 对话风格要求 1. 语气自然像朋友聊天不要念百科。 2. 可以吐槽但不要真正攻击对方。 3. 句子不要过长控制在两三句话以内。 4. 不要提醒对方“我是 AI”。 5. 如果用户提到危险、违规、欺骗内容明确拒绝并转移话题。 这是角色背景但不是你需要背下来的知识你要做的是带着这种性格 去聊天而不是回答关于自己有多厉害的问题。角色卡不要写成“角色小传”而要写成“行为准则”。模型不需要背故事它需要知道怎么说话。5.2 FastAPI 对话接口代码新建项目目录结构如下sunset-chat/ ├── app.py ├── role_card.txt ├── static/ │ └── index.html └── requirements.txt先写后端app.py# app.py from fastapi import FastAPI from fastapi.responses import FileResponse, JSONResponse from fastapi.staticfiles import StaticFiles from pydantic import BaseModel from openai import OpenAI app FastAPI() # 模型服务的地址按实际配置修改 MODEL_BASE_URL http://127.0.0.1:8001/v1 MODEL_NAME sunset-model client OpenAI(base_urlMODEL_BASE_URL, api_keyEMPTY) # 读取角色卡 with open(role_card.txt, r, encodingutf-8) as f: ROLE_CARD f.read().strip() class ChatMessage(BaseModel): content: str class ChatRequest(BaseModel): message: str class ChatResponse(BaseModel): reply: str audio_url: str app.post(/api/chat) async def chat(req: ChatRequest): messages [ {role: system, content: ROLE_CARD}, {role: user, content: req.message}, ] try: resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, temperature0.8, max_tokens300, ) reply resp.choices[0].message.content.strip() except Exception as e: return JSONResponse(status_code502, content{error: str(e)}) return ChatResponse(replyreply) app.get(/) async def index(): return FileResponse(static/index.html) app.mount(/static, StaticFiles(directorystatic), namestatic)这段代码的关键点MODEL_BASE_URL指向兼容 OpenAI 接口的模型服务地址。角色卡放在系统消息里确保每次对话都带着角色人格。temperature设成 0.8让回复自然但不至于太散。异常统一捕获方便前端拿到明确错误信息。不要在这一步把 TTS 接进去先把纯文本流程跑通再逐步加语音。工程上这叫“先打通主干再加枝叶”。6. 语音合成让角色开口说话对话接口返回文本后下一步就是让角色把话说出来。这一步在工程上叫 TTS 结果与对话接口的异步集成。6.1 本地 TTS 方案edge-tts 演示edge-tts是一个 Python 库可以直接把文本合成为 mp3 文件。它调用的是微软边缘服务接口对个人开发和 demo 来说非常方便。如果是正式商用请换成有明确授权的 TTS 服务。写一个独立的 TTS 服务脚本用 FastAPI 暴露接口# tts_service.py import asyncio import uuid import edge_tts from fastapi import FastAPI from fastapi.responses import FileResponse from pydantic import BaseModel app FastAPI() OUTPUT_DIR static/audio VOICE zh-CN-XiaoxiaoNeural # 可换音色 class TTSRequest(BaseModel): text: str app.post(/api/tts) async def tts(req: TTSRequest): file_id str(uuid.uuid4()) output_path f{OUTPUT_DIR}/{file_id}.mp3 communicate edge_tts.Communicate(req.text, VOICE) await communicate.save(output_path) return {audio_url: f/static/audio/{file_id}.mp3}然后在app.py中把 TTS 调用接进/api/chatimport requests # 需要在开头导入 # 修改后的 chat 接口段落 app.post(/api/chat) async def chat(req: ChatRequest): messages [ {role: system, content: ROLE_CARD}, {role: user, content: req.message}, ] try: resp client.chat.completions.create( modelMODEL_NAME, messagesmessages, temperature0.8, max_tokens300, ) reply resp.choices[0].message.content.strip() except Exception as e: return JSONResponse(status_code502, content{error: str(e)}) # 调用 TTS try: tts_resp requests.post( http://127.0.0.1:8002/api/tts, json{text: reply}, timeout30, ) audio_url tts_resp.json().get(audio_url, ) except Exception: audio_url return ChatResponse(replyreply, audio_urlaudio_url)这里把 TTS 服务独立部署在 8002 端口对话服务通过 HTTP 调用它。好处是解耦以后换 TTS 供应商只需要改tts_service.py对话逻辑不受影响。6.2 TTS 的工程坑TTS 最容易踩的坑有两个一是文本长度。角色回复可能是一整段直接交给 TTS 会合成出“念课文”的平淡效果。更好的做法是对话模型生成时控制输出长度或者在后端做简单分段遇到句号、问号就拆开再合成。二是音频路径和跨域问题。前端通过 URL 访问音频文件时如果前端页面和后端不在同一个端口会触发跨域。最简单的方法是前后端同源统一让 FastAPI 托管前端页面和音频文件前端只请求同一个域名下的接口。7. 前端聊天页实现前端页面需要完成三件事渲染聊天记录、发送用户消息、播放返回的语音。我用原生 HTML CSS JavaScript 实现不引入构建工具。创建static/index.html!DOCTYPE html html langzh-CN head meta charsetUTF-8 meta nameviewport contentwidthdevice-width, initial-scale1.0 titleSunset Chat/title style * { box-sizing: border-box; } body { font-family: PingFang SC, Microsoft YaHei, sans-serif; background: #f5f3fa; margin: 0; padding: 20px; } .chat-container { max-width: 640px; margin: 0 auto; background: white; border-radius: 16px; box-shadow: 0 4px 20px rgba(0,0,0,0.08); overflow: hidden; } .chat-header { background: #7c6bb5; color: white; padding: 16px 20px; font-size: 18px; font-weight: 600; } .chat-messages { height: 480px; overflow-y: auto; padding: 20px; background: #faf8ff; } .msg { margin-bottom: 16px; max-width: 80%; } .msg.user { margin-left: auto; text-align: right; } .msg.bot { margin-right: auto; } .bubble { display: inline-block; padding: 10px 14px; border-radius: 16px; background: white; box-shadow: 0 1px 4px rgba(0,0,0,0.06); } .msg.user .bubble { background: #7c6bb5; color: white; } .msg .meta { font-size: 12px; color: #999; margin-bottom: 4px; } .audio-btn { margin-top: 6px; font-size: 13px; color: #7c6bb5; cursor: pointer; background: none; border: none; text-decoration: underline; } .chat-input { display: flex; gap: 10px; padding: 14px; border-top: 1px solid #eee; } .chat-input input { flex: 1; border: 1px solid #ddd; border-radius: 24px; padding: 10px 16px; outline: none; font-size: 14px; } .chat-input button { border: none; background: #7c6bb5; color: white; padding: 10px 20px; border-radius: 24px; font-size: 14px; cursor: pointer; } /style /head body div classchat-container div classchat-header余晖烁烁 · 在线/div div classchat-messages idmessages/div div classchat-input input typetext idinput placeholder想对余晖烁烁说点什么 button idsendBtn发送/button /div /div script const messagesBox document.getElementById(messages); const inputBox document.getElementById(input); function addMessage(role, text) { const div document.createElement(div); div.className msg role; div.innerHTML div classbubble text /div; messagesBox.appendChild(div); messagesBox.scrollTop messagesBox.scrollHeight; } function addAudioButton(url) { if (!url) return; const div document.createElement(div); div.className msg bot; div.innerHTML button classaudio-btn onclickplayAudio(\ url \)播放语音/button; messagesBox.appendChild(div); } function playAudio(url) { const audio new Audio(url); audio.play(); } async function send() { const text inputBox.value.trim(); if (!text) return; inputBox.value ; addMessage(user, text); const response await fetch(/api/chat, { method: POST, headers: {Content-Type: application/json}, body: JSON.stringify({message: text}) }); if (!response.ok) { addMessage(bot, 请求失败请检查后端服务状态。); return; } const data await response.json(); addMessage(bot, data.reply); addAudioButton(data.audio_url); } document.getElementById(sendBtn).addEventListener(click, send); inputBox.addEventListener(keydown, function(e) { if (e.key Enter) send(); }); /script /body /html这个前端页面的思路是用户输入后点击发送通过 fetch 请求/api/chat拿到reply和audio_url后把文字渲染到聊天框如果有音频地址就加一个“播放语音”按钮。这里对 XSS 做一点提示上面示例用innerHTML直接渲染文本对 demo 来说能跑但如果做公开产品必须改成用textContent渲染防止用户输入注入恶意脚本。这个点我在后面最佳实践部分还会强调。8. 本地联调与部署上线代码写完后按照下面顺序启动服务就能看到完整效果。8.1 启动顺序第一步启动模型服务。这步需要在你的模型服务目录里执行端口保持 8001。第二步启动 TTS 服务uvicorn tts_service:app --host 0.0.0.0 --port 8002第三步启动后端主服务uvicorn app:app --host 0.0.0.0 --port 8000打开浏览器访问http://127.0.0.1:8000/应该能看到聊天页面。8.2 验证接口后端启动后建议先用 curl 验证接口排除前端问题curl -X POST http://127.0.0.1:8000/api/chat \ -H Content-Type: application/json \ -d {message:你好还记得你的朋友吗}预期返回 JSON{ reply: 当然记得朋友对我来说比什么荣誉都重要。, audio_url: /static/audio/xxxx.mp3 }如果返回502说明模型服务地址或模型名称配置不对查看命令终端输出。如果audio_url为空说明 TTS 服务没启动或者请求超时。8.3 用 Docker Compose 一键部署可选如果你想在服务器上部署可以用 Docker Compose 把三个服务编排起来。先写三个服务的 Dockerfile然后用下面这个 compose 文件# docker-compose.yml version: 3.9 services: model-api: image: your-model-server-image ports: - 8001:8001 tts: build: . command: uvicorn tts_service:app --host 0.0.0.0 --port 8002 volumes: - ./static:/app/static ports: - 8002:8002 app: build: . command: uvicorn app:app --host 0.0.0.0 --port 8000 depends_on: - model-api - tts environment: - MODEL_BASE_URLhttp://model-api:8001/v1 ports: - 8000:8000注意app.py里读取模型服务地址的代码需要改成从环境变量读取import os MODEL_BASE_URL os.getenv(MODEL_BASE_URL, http://127.0.0.1:8001/v1)这样在 Docker 环境里服务名model-api会自动解析到模型服务容器。部署上线时建议前置一层 Nginx把 80 端口转发到 8000 端口这样访客不需要带端口号访问。同时 Nginx 还可以帮你做静态文件缓存和 HTTPS 终止。9. 常见问题与排查思路做这套东西的时候有几个问题出现频率非常高整理成表格方便快速定位问题现象可能原因排查方式解决方案访问页面 404FastAPI 没找到static/index.html查看项目目录结构确认工作目录正确用uvicorn app:app在项目根目录启动聊天接口返回 502模型服务地址错误或服务未启动curl 模型服务的/v1/models接口确认模型服务端口和MODEL_BASE_URL回复内容完全不像角色角色卡 Prompt 写得太短检查 system prompt 是否被加载补充说话风格和禁止项参考第 5.1 节回复到一半中断max_tokens太小查看返回的finish_reason增大max_tokens返回没有audio_urlTTS 服务没启动或请求超时单独 curl TTS 接口启动 TTS 服务确认端口前端页面播放语音没声音跨域问题或路径错误打开浏览器开发者工具查看网络面板确认音频 URL 可直接访问前后端保持同源接口响应很慢模型服务推理慢或 TTS 串行等待记录每步耗时先关掉 TTS 测试换成更快的模型或并发调用 TTS角色多轮后会“失忆”没有传历史消息列表看后端 messages 是否只传了一轮将多轮消息保存并拼接到 messages 中这里特别说明历史消息问题。示例代码为了保持简短只传了当前用户消息和系统角色卡。但真实场景里用户上一句说“我喜欢音乐”下一句说“那你推荐一首”模型如果没记住上文会答非所问。解决办法是前端或后端维护消息历史数组每次请求把最近 N 条消息都传给模型。维护历史消息时要设置上限。比如只保留最近 20 条超出就丢弃最早的。否则请求体越来越大既增加模型服务压力也拉长响应时间。10. 最佳实践与工程建议到这里一个可运行的角色互动应用已经能跑通了。但如果要做成真实产品以下几点值得认真对待。10.1 角色卡要持续迭代第一次写的角色卡效果通常不稳定。最好的做法是准备 20 到 30 条测试用例覆盖普通聊天、角色相关提问、敏感话题、连续多轮对话每次改完 Prompt 后跑一遍用例。角色卡迭代应该像代码迭代一样有版本记录不要改完就忘。10.2 强调内容安全与合规边界角色互动应用面向用户时内容安全是第一优先级。必须做三件事第一输入和输出都做敏感内容过滤。用户可能输入引导性内容模型也可能产生意外回复。在对接模型服务前和后端返回前端前各加一道过滤或要求模型服务端启用内容审核。第二涉及角色 IP 的公开产品要获得授权。以“余晖烁烁”为例角色形象和名称属于版权方个人学习没问题公开商业化必须确认授权边界。这里不是法律建议但技术产品上线前应该主动排查 IP 风险。第三公开部署必须做用户访问控制、使用协议、举报反馈入口。如果提供语音合成能力还要防止用户把语音用于诈骗、伪造身份等非法用途。10.3 控制成本和延迟模型服务和 TTS 都会产生成本和延迟。建议对话模型使用流式输出用户看到第一个字的时间会快很多。TTS 请求只在用户点击播放时才触发或者在前端缓存已经生成过的音频。高频问题可以做简单缓存命中缓存直接返回减少模型调用。10.4 前端渲染使用 textContent示例代码用innerHTML是为了简洁但存在 XSS 风险。正式项目中用户输入的内容绝不能直接插入 HTML要使用textContent或成熟的模板引擎并对模型输出做同样的处理。11. 总结与下一步回到开头那句“Can I get a kisssunset”。这句话的价值不在于表面的表达而在于它代表了一种需求用户希望角色有回应。用本文的方法你可以用角色卡、对话接口、TTS 和前端页面把这种“回应”做成一个可运行的产品原型。技术栈不复杂核心在于角色人格的稳定设计和工程链路的串联。跑通文本聊天后下一步值得尝试的方向是为角色加入多轮记忆让它能够记住用户偏好接入实时语音识别让用户可以直接说话而不是打字把单角色升级成多角色群聊让不同角色共享上下文。每往前走一步产品的沉浸感受都会明显提升。如果你准备用这套思路做自己的项目建议先保存这个 demo然后从一个你最熟悉的角色开始改 Prompt设计一套你自己的测试用例。把第一版跑稳定再谈扩展。