第一次刷到这类“AI角色陪伴”主题的创作时,很多人第一眼注意到的是画面和台词,真正让我停下来的却是藏在背后的那套交互链路:一个虚拟的少女角色,能在你输入一句话后给出符合人设的回应,还能用带语气的声音读出来,甚至让整个页面的背景音乐随心情切换。以“海屿”这个夏末海边主题角色为例,把这条链路拆开看,核心并不神秘,用一套公共大模型API加几个开源库就能在本地搭出来。
这篇文章会从零构建一个可运行的AI虚拟角色陪伴应用:角色叫“海屿”,设定是夏末海边的咖啡馆兼职店员,氛围参考《海屿你》这类轻柔海边曲目的表达方向。读完你会掌握角色人设Prompt设计、LLM对话接入、轻量情绪判断、TTS语音合成,以及Web端前后端联动这几块内容,也能直接复用代码改造出自己的角色项目。适用人群包括:想给聊天机器人加人设的产品或后端同学、对AI Agent和AI工程实践感兴趣的开发者,以及刚接触大模型API想练手的入门者。全程用Python编写,只依赖FastAPI、OpenAI SDK、edge-tts等常规工具,不需要自己训练模型,也不需要昂贵的显卡。
1. 背景与核心概念
1.1 什么是AI虚拟角色陪伴应用
AI虚拟角色陪伴应用,通俗说就是给大语言模型套上一张“人设卡”,再通过语音、情绪反馈、界面氛围这些包装,让用户觉得自己是在和一个有名字、有性格、有记忆线索的虚拟角色互动,而不是在和一个通用问答机器人聊天。
从技术角度看,这类应用通常由四层组成。第一层是人设设定层,对应的是System Prompt,也就是角色卡,它决定模型“以谁的身份”说话。第二层是对话引擎层,负责把用户消息拼上历史记录,调用大模型接口,拿到回复文本。第三层是理解与表达层,包括情绪识别、语音合成、表情包或动作渲染等。第四层是呈现层,也就是用户实际看到的聊天页面、音频播放器和氛围切换效果。四层各自独立,又通过一个业务接口串起来。
在做陪伴向产品时,角色感是灵魂。通用助手强调的是“准确、高效”,而虚拟角色强调的是“稳定的人设、有温度的表达、可感知的情绪”。这也是为什么直接套一个ChatGPT窗口做角色互动会显得很别扭——缺少了人设约束和表达层包装。
1.2 为什么这类应用值得亲手实现
不是所有聊天机器人都需要“角色感”,但一旦开始做角色感,你会发现自己必须亲手调过很多细节才真正理解背后的工程问题:为什么同样的提示词,模型聊到十几轮之后会跳出人设?为什么简单的关键词情绪判断在口语化文本里会误判?为什么TTS在某些情况下会让角色显得机械?这些问题靠看文档很难形成体感,最好的方式就是先把一个最小可运行项目跑通,再按照自己遇到的场景慢慢迭代。
这个方向同时也是学习AI Agent的合适起点。陪伴类角色天然需要多轮对话记忆、按人设约束输出、调用外部能力(语音合成、背景音乐、知识库)这几件事,这些能力正好是Agent工程的重要组成部分。换句话说,你做完这个Demo,不只是学会了一个玩具,而是掌握了一套可以迁移到智能客服、虚拟主播、IP数字人等项目上的基础结构。
1.3 本文示例场景说明
为了让代码有落点,本文设定一个名叫“海屿”的虚拟角色。她的设定是22岁,在海边小城一家咖啡馆做兼职,喜欢收集贝壳、拍晚霞,偶尔会哼几句海边小调,说话轻快阳光又有点小迷糊。场景氛围参考夏末海边主题创作的方向:晚风、退潮、汽水、回忆。我们要做的,就是让这个角色在一个网页里真正“活”起来。
这里也想说明一个经验:做AI虚拟角色最忌人设模糊。角色必须给出年龄、职业、性格、说话风格、喜欢的话题,甚至一些记忆线索,否则模型很容易把回复写成“披着人设皮的通用助手”,聊两三句就暴露原型。后面第4章我们会在角色卡代码里实际体会这一点。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 系统架构与功能设计
2.1 功能需求拆解
一个够用的陪伴对话应用,最低限度需要四个功能:
- 文本对话:用户发消息,角色按照人设回复。
- 情绪感知:根据用户当前输入,判断情绪倾向,用于后续调整回复语气和氛围。
- 语音朗读:把角色回复转成音频播放,让交流更有“真人在说话”的感觉。
- 氛围联动:在不同情绪下切换背景音乐或页面主题,让整个页面有呼吸感。
第2点听起来复杂,但在Demo阶段完全可以用情感词典做轻量判断,不必一上来就接入大模型分类器。字典方案的准确率虽然有限,但足够演示“情绪-氛围”联动链路,而且便于理解和扩展。
2.2 整体架构与数据流
采用最经典的前后端分离结构,数据流如下:
code复制浏览器页面(index.html)
│ POST /api/chat
▼
FastAPI 接口层
│
├── 取出角色卡 SYSTEM_PROMPT + 历史消息
├── 调用大模型 API 得到回复文本
├── 对用户消息做情绪识别
├── 调用 TTS 把回复转成 mp3
└── 返回 reply + emotion + audio_url
│
▼
浏览器显示文字、播放音频、按情绪切换背景音乐
简单说,后端做三件事:汇聚消息和角色卡后请求大模型、分析情绪、把回复文本转成语音文件。真正的角色表现力来自Prompt设计,而不是模型魔法。
2.3 技术选型说明
技术选型的原则是“够用、好改、网上资料多”。最终选择如下:
- Python 3.10+:AI工程生态最成熟的编程语言,示例代码也最丰富。
- FastAPI:轻量Web框架,自带接口文档,适合快速搭建AI服务。
- OpenAI Python SDK:统一封装OpenAI兼容协议,可以对接国内外多种大模型服务商,换模型时只需改配置。
- edge-tts:免费的在线语音合成库,由Python调用微软Edge在线接口,中文音色质量不错,适合Demo和原型验证。
- 原生HTML/CSS/JavaScript:零构建成本,不需要Node工具链,打开就能跑,让读者把注意力放在后端核心逻辑上。
如果将来要上生产,edge-tts可以换成云厂商TTS或本地推理TTS,直连大模型的调用可以换成带有网关、缓存、审计能力的中间层。这些将在第7章详细展开。
3. 环境准备与版本说明
3.1 运行环境要求
演示环境需要满足三个条件:本地能运行Python、能访问所选大模型的API、能访问edge-tts依赖的在线接口。如果你所在的部署环境完全离线,edge-tts会失效,需要换成PaddleSpeech或Sherpa-Onnx一类离线语音合成方案。
机器配置方面,这是一个非常轻量的Web服务,普通开发本机就能流畅运行,不要求GPU。版本方面,建议Python不低于3.10,下文使用的几个依赖库我会给出一个不小于的版本区间。你可以直接按这个版本安装,也可以使用更新版本,因为大版本API基本兼容。
3.2 创建项目与依赖
先创建项目目录和静态资源目录:
bash复制mkdir ai-haiyu && cd ai-haiyu
mkdir static
然后新建requirements.txt文件:
txt复制fastapi>=0.110
uvicorn>=0.29
openai>=1.30
edge-tts>=6.1.10
python-dotenv>=1.0
执行安装命令:
bash复制pip install -r requirements.txt
这里要说明一下,后面代码中的大模型接入使用的是OpenAI SDK对象。它不只能连OpenAI官方服务,也支持所有提供“OpenAI兼容接口”的模型服务商,只需要调整base_url和model名即可,这是目前比较通用的接入方式。
3.3 大模型API配置
在项目根目录创建.env文件,用来保存密钥和模型配置:
properties复制# .env
LLM_API_KEY=你的Key
LLM_BASE_URL=https://api.openai.com/v1
LLM_MODEL=gpt-4o-mini
TTS_VOICE=zh-CN-XiaoyiNeural
这里的关键点是:只要服务商提供OpenAI兼容接口,把LLM_BASE_URL和LLM_MODEL换成对应值即可。例如使用DeepSeek、Moonshot、智谱或国内厂商的兼容端点时,通常只需要调整这两项,代码不需要大改。千万不要把真实的API Key提交到Git仓库,建议在.gitignore中忽略.env文件。如果你用的模型不支持OpenAI兼容协议,就需要把llm_client.py里的调用改成对应厂商的SDK写法,整体思路仍然一样。
4. 核心模块实现拆解
4.1 角色卡设计与System Prompt
角色卡本质上是一段结构化的System Prompt,它决定模型“以谁的身份”说话。写角色卡有三个层次:身份事实、说话风格、互动规则。身份事实包括年龄、职业、背景故事;说话风格负责让模型输出带口癖或语气特点;互动规则限制回复长度、禁止事项、如何接住情绪。
下面是角色卡代码,文件路径为character_card.py:
python复制# character_card.py
CHARACTER_CARD = {
"name": "海屿",
"age": "22",
"background": "海边小城一家咖啡馆的兼职店员,喜欢收集贝壳、拍晚霞,偶尔会哼几句海边小调。",
"personality": "元气、温柔、有点小迷糊,但对大海和音乐有自己的执着。",
"speaking_style": "语气轻快阳光,喜欢用海边相关的比喻,比如'今天的风像刚从冰箱拿出来的汽水一样清爽'。",
"topics": ["夏末的海风", "音乐", "甜品", "日出日落", "捡贝壳"],
"memories": ["你是在夏末一个傍晚走进店里的客人。", "她答应过教你分辨潮汐和风向。"],
}
SYSTEM_PROMPT = f"""你正在扮演一位名叫{CHARACTER_CARD['name']}的虚拟伙伴。
【人设信息】
- 年龄:{CHARACTER_CARD['age']}
- 背景:{CHARACTER_CARD['background']}
- 性格:{CHARACTER_CARD['personality']}
- 说话风格:{CHARACTER_CARD['speaking_style']}
- 喜欢的话题:{', '.join(CHARACTER_CARD['topics'])}
- 记忆线索:{', '.join(CHARACTER_CARD['memories'])}
【互动规则】
1. 每次回复控制在100字以内,像朋友之间自然聊天。
2. 先接住用户分享的情绪,再展开回应。
3. 当用户提到夏末、海边、歌曲《海屿你》等话题时,主动用大海的意象回应,让对话有氛围感。
4. 不要总问'有什么可以帮你的',不要机械式回复。
5. 全程不要暴露自己是AI、语言模型或虚拟程序。
6. 禁止输出涉黄、涉暴、涉未成年人不良内容,碰到这类话题要温和地转移话题。
"""
这段Prompt里值得注意的几个设计点。第一,把角色信息以结构化字段写入,方便后续维护,比如要给海屿增加职业或新记忆,只需修改字典而不需要动Prompt模板。第二,“记忆线索”字段会让角色在开场阶段自带关系感,避免每轮对话都像陌生人。第三,互动规则第5条和第6条是安全边界,既保证角色不“露馅”,也防止模型生成不合规内容。
4.2 LLM对话接入封装
对话接入的核心是把用户消息数组组织成符合大模型接口要求的格式,然后调用chat.completions.create。这里的messages是OpenAI兼容协议中约定好的结构,每个元素包含role(system/user/assistant)和content字段。
下面实现一个客户端封装,文件路径为llm_client.py:
python复制# llm_client.py
from openai import OpenAI
from character_card import SYSTEM_PROMPT
from config import API_KEY, BASE_URL, MODEL_NAME
client = OpenAI(api_key=API_KEY, base_url=BASE_URL)
def chat_with_character(messages: list) -> str:
full_messages = [{"role": "system", "content": SYSTEM_PROMPT}] + messages
resp = client.chat.completions.create(
model=MODEL_NAME,
messages=full_messages,
temperature=0.8,
max_tokens=300,
)
return resp.choices[0].message.content.strip()
这里temperature设置为0.8,属于偏创造性的范围,比较适合角色扮演场景。如果设置过高,比如1.3以上,回复容易跑偏甚至跳出人设;设置过低,到0.2以下,回复又可能显得机械。实际项目中,你可以针对自己的角色风格做一次温度小测试。max_tokens设为300,是限制单次回复文本长度,防止角色长篇大论。
还有一个细节:每次请求都会把角色卡SYSTEM_PROMPT放在历史消息最前面。这样虽然调用成本略高,但能保证模型每一轮都记得自己是谁,是角色稳定性最简单、最可靠的手段。
4.3 轻量情绪识别
情绪识别模块的作用,是判断用户当前输入是开心、低落还是平静,供前端切换背景音乐和氛围。在Demo阶段,我们不会调用额外的大模型或分类服务,而是用一个情感词典去统计命中词数,简单直观且完全可控。
文件路径为emotion.py:
python复制# emotion.py
POSITIVE_WORDS = [
"开心", "高兴", "喜欢", "期待", "哇", "哈哈", "好棒", "nice", "太香", "好耶", "温柔", "治愈"
]
NEGATIVE_WORDS = [
"难过", "伤心", "累", "烦", "焦虑", "emo", "哭", "失望", "崩溃", "好难", "孤独", "压力"
]
ENERGY_WORDS = [
"冲", "出发", "一起", "马上", "走", "打卡"
]
def analyze_emotion(text: str) -> dict:
text_lower = text.lower()
positive = sum(1 for w in POSITIVE_WORDS if w.lower() in text_lower)
negative = sum(1 for w in NEGATIVE_WORDS if w.lower() in text_lower)
energy = sum(1 for w in ENERGY_WORDS if w.lower() in text_lower)
if positive > negative:
mood = "开心"
elif negative > positive:
mood = "低落"
else:
mood = "平静"
return {
"mood": mood,
"positive_score": positive,
"negative_score": negative,
"energy_score": energy,
}
这种方案的局限也很明显。比如用户发“心情一般般”,其实没有明显情绪词,就会判断为平静;用户发反讽句子时,也容易被误判。但这不影响我们演示联调流程,因为情绪识别的输出只是影响背景音乐切换,并不会影响大模型回复。如果后续要做更精准的情绪分类,可以换成一个文本分类模型,或者直接用大模型打分,但这就需要考虑成本和延迟。
4.4 语音合成接入
语音合成使用edge-tts,它的调用方式是构造Communicate对象,然后异步保存为mp3文件。注意:edge-tts的save任务是异步的,需要借助asyncio来运行。我们先封装一个同步函数,方便后端直接调用。
文件路径为tts.py:
python复制# tts.py
import asyncio
import edge_tts
from config import TTS_VOICE
async def _synthesize(text: str, output_file: str) -> None:
communicate = edge_tts.Communicate(text, TTS_VOICE)
await communicate.save(output_file)
def text_to_speech(text: str, output_file: str) -> str:
asyncio.run(_synthesize(text, output_file))
return output_file
这里隐藏着一个常见的坑:如果你在FastAPI的async接口里直接调用text_to_speech,会触发“asyncio.run cannot be called from a running event loop”的报错。解决方法很直接,让调用text_to_speech的业务接口使用同步def定义,FastAPI会把同步接口放到线程池里执行,就能安全使用asyncio.run了。这个坑我们会在第6章再回顾。
TTS_VOICE变量来自config.py,常用中文音色包括zh-CN-XiaoyiNeural、zh-CN-XiaoxiaoNeural等,你可以按喜好配置。值得提醒的是,edge-tts本质上是请求微软在线接口,部署环境必须能访问外网,且隐私要求高的项目应谨慎使用。
5. 完整实战:构建“海屿”对话应用
5.1 项目结构
现在我们把所有模块合并成一个完整项目。最终目录结构如下:
text复制ai-haiyu/
├── .env
├── requirements.txt
├── config.py
├── character_card.py
├── emotion.py
├── llm_client.py
├── tts.py
├── main.py
└── static/
├── index.html
├── bgm_peace.mp3 # 自行准备
├── bgm_happy.mp3 # 自行准备
└── bgm_sad.mp3 # 自行准备
bgm_peace.mp3、bgm_happy.mp3、bgm_sad.mp3这几个音乐文件不会在代码里自动生成,需要你使用自己的原创音乐或购买授权后放入static目录。如果暂时没有音频文件,应用也能正常工作,只是背景音乐切换会静默失败,不影响聊天和语音朗读。
5.2 全局配置代码
config.py用来读取.env配置,后续所有模块都会从这里拿参数。
python复制# config.py
import os
from dotenv import load_dotenv
load_dotenv()
API_KEY = os.getenv("LLM_API_KEY", "")
BASE_URL = os.getenv("LLM_BASE_URL", "https://api.openai.com/v1")
MODEL_NAME = os.getenv("LLM_MODEL", "deepseek-chat")
TTS_VOICE = os.getenv("TTS_VOICE", "zh-CN-XiaoyiNeural")
这段代码在进程启动时导入.env文件。注意,.env文件不要提交到Git仓库,同时API_KEY为空时会直接导致大模型调用报错,这是有意为之,提示你务必先完成配置。
5.3 后端接口代码
后端入口main.py把前面所有模块串起来。它提供两个路由:GET /用于返回前端页面,POST /api/chat用于处理对话请求。
python复制# main.py
import uuid
from typing import List, Optional
from fastapi import FastAPI, HTTPException
from fastapi.responses import FileResponse
from fastapi.staticfiles import StaticFiles
from pydantic import BaseModel, Field
from character_card import SYSTEM_PROMPT
from emotion import analyze_emotion
from llm_client import chat_with_character
from tts import text_to_speech
app = FastAPI(title="AI海屿")
app.mount("/static", StaticFiles(directory="static"), name="static")
class ChatRequest(BaseModel):
message: str
history: List[dict] = Field(default_factory=list)
class ChatResponse(BaseModel):
reply: str
emotion: dict
audio_url: Optional[str] = ""
@app.get("/")
def index():
return FileResponse("static/index.html")
@app.post("/api/chat", response_model=ChatResponse)
def chat(req: ChatRequest):
try:
# 组装多轮历史消息
messages = []
for item in req.history:
role = item.get("role", "user")
content = item.get("content", "").strip()
if content:
messages.append({"role": role, "content": content})
# 1. 调用大模型获取角色回复
reply = chat_with_character(messages)
# 2. 对用户当前输入做情绪识别
emotion = analyze_emotion(req.message)
# 3. 将回复转成语音文件
audio_url = ""
try:
filename = f"static/reply_{uuid.uuid4().hex[:8]}.mp3"
text_to_speech(reply, filename)
audio_url = f"/{filename}"
except Exception as e:
print("TTS失败:", e)
return ChatResponse(reply=reply, emotion=emotion, audio_url=audio_url)
except Exception as e:
raise HTTPException(status_code=500, detail=f"对话失败: {e}")
代码中的流程顺序是刻意的:先做对话,再做情绪识别,最后做TTS。情绪识别放在对话之后,是为了避免情绪识别错误影响角色回复;TTS放在最后,则是因为如果TTS失败,也不应影响文字回复回传。另外注意每个语音文件都用uuid命名,可以避免多用户同时请求时互相覆盖。
5.4 前端聊天页面
前端页面放在static/index.html中。页面本身是单文件,包含样式、聊天结构和JavaScript逻辑。下面给出完整代码:
html复制<!-- static/index.html -->
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>AI海屿 · 夏末海边对话</title>
<style>
* { margin: 0; padding: 0; box-sizing: border-box; }
body {
font-family: "Microsoft YaHei", "PingFang SC", sans-serif;
min-height: 100vh;
background: linear-gradient(160deg, #0f2027, #203a43, #2c5364);
display: flex;
justify-content: center;
align-items: center;
padding: 20px;
}
.app {
width: 420px;
max-width: 100%;
height: 680px;
background: rgba(255, 255, 255, 0.92);
border-radius: 20px;
display: flex;
flex-direction: column;
overflow: hidden;
box-shadow: 0 20px 60px rgba(0, 0, 0, 0.35);
}
.header {
background: #e8f7ff;
padding: 16px 20px;
border-bottom: 1px solid #d0e6f5;
}
.header h1 { font-size: 18px; color: #1f3a52; }
.header p { font-size: 12px; color: #5f7f9a; margin-top: 4px; }
.chat-box {
flex: 1;
overflow-y: auto;
padding: 16px;
background: #f7fbfe;
}
.msg { margin-bottom: 12px; display: flex; }
.msg.user { justify-content: flex-end; }
.msg .bubble {
max-width: 75%;
padding: 10px 14px;
border-radius: 14px;
font-size: 14px;
line-height: 1.6;
white-space: pre-wrap;
word-break: break-word;
}
.msg.user .bubble {
background: #d0f0ff;
border-bottom-right-radius: 4px;
}
.msg.bot .bubble {
background: #ffffff;
border: 1px solid #dcebf5;
border-bottom-left-radius: 4px;
}
.audio-row { margin-top: 6px; text-align: right; }
.audio-row audio { width: 180px; height: 30px; }
.mood-tag {
display: inline-block;
font-size: 12px;
color: #1f3a52;
background: #e8f1fa;
padding: 2px 10px;
border-radius: 10px;
margin-top: 8px;
}
.input-area {
display: flex;
gap: 8px;
padding: 12px;
border-top: 1px solid #dcebf5;
background: #ffffff;
}
.input-area input {
flex: 1;
padding: 10px 14px;
border: 1px solid #cbd8e5;
border-radius: 20px;
outline: none;
font-size: 14px;
}
.input-area button {
padding: 10px 18px;
border: none;
border-radius: 20px;
background: #2c5364;
color: #fff;
cursor: pointer;
font-size: 14px;
}
.input-area button:disabled {
background: #9db4c4;
cursor: not-allowed;
}
</style>
</head>
<body>
<audio id="bgm" loop hidden></audio>
<div class="app">
<div class="header">
<h1>海屿 · 你的夏末限定陪伴</h1>
<p>她是你夏末傍晚在海边咖啡馆遇见的女孩</p>
</div>
<div class="chat-box" id="chatBox">
<div class="msg bot">
<div class="bubble">嗨,又见面啦!今天海边退潮很早,我刚好捡到一枚很漂亮的贝壳呢。你呢,最近过得怎么样?</div>
</div>
</div>
<div class="input-area">
<input id="input" type="text" placeholder="和海屿说点什么吧……" autocomplete="off">
<button id="sendBtn">发送</button>
</div>
</div>
<script>
const chatBox = document.getElementById("chatBox");
const input = document.getElementById("input");
const sendBtn = document.getElementById("sendBtn");
const bgm = document.getElementById("bgm");
const history = [];
function appendMessage(role, content, audioUrl, emotion) {
const row = document.createElement("div");
row.className = "msg " + role;
const bubble = document.createElement("div");
bubble.className = "bubble";
bubble.textContent = content;
row.appendChild(bubble);
if (emotion && role === "bot") {
const moodTag = document.createElement("div");
moodTag.className = "mood-tag";
moodTag.textContent = "海屿感知:" + emotion.mood;
bubble.appendChild(moodTag);
}
if (role === "bot" && audioUrl) {
const audioRow = document.createElement("div");
audioRow.className = "audio-row";
audioRow.innerHTML = `<audio controls src="${audioUrl}"></audio>`;
bubble.appendChild(audioRow);
}
chatBox.appendChild(row);
chatBox.scrollTop = chatBox.scrollHeight;
}
async function sendMessage() {
const text = input.value.trim();
if (!text) return;
appendMessage("user", text);
history.push({ role: "user", content: text });
input.value = "";
sendBtn.disabled = true;
try {
const resp = await fetch("/api/chat", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message: text, history: history })
});
const data = await resp.json();
appendMessage("bot", data.reply, data.audio_url, data.emotion);
history.push({ role: "assistant", content: data.reply });
// 根据情绪切换背景音乐
const mood = data.emotion.mood;
let bgmSrc = "";
if (mood === "开心") bgmSrc = "/static/bgm_happy.mp3";
else if (mood === "低落") bgmSrc = "/static/bgm_sad.mp3";
else bgmSrc = "/static/bgm_peace.mp3";
if (bgmSrc) {
bgm.src = bgmSrc;
bgm.play().catch(() => {});
}
} catch (err) {
console.error(err);
appendMessage("bot", "海屿有点卡壳了……稍等再试一次?");
} finally {
sendBtn.disabled = false;
}
}
sendBtn.addEventListener("click", sendMessage);
input.addEventListener("keydown", (e) => {
if (e.key === "Enter") sendMessage();
});
</script>
</body>
</html>
这段前端逻辑的重点在于history数组。每次发送时,会把用户消息和助手消息都压入history,随后整体发给后端,从而支持多轮对话。背景音乐切换依赖后端返回的emotion.mood字段,你在前端能看到“开心”“低落”“平静”三档情绪对应对应的音乐文件。实际部署时,建议给背景音乐播放器加入切换淡入淡出效果,可以让氛围过渡更平滑。
5.5 启动与验证
在项目根目录执行:
bash复制uvicorn main:app --host 0.0.0.0 --port 8000 --reload
启动成功后,浏览器访问http://localhost:8000,可以看到聊天页面。首次打开时,页面会先显示海屿的问候语。在输入框输入“今天好累啊”,回车后等待片刻,后端会依次完成大模型调用、情绪识别和语音合成,然后页面出现角色回复、情绪标签和可播放的语音条。如果static目录下放好了bgm_sad.mp3,背景音乐会自动切换为低落氛围版本;输入“好开心,明天就要去看海了!”,情绪会变成开心,背景音乐对应切换,语音条也会重新生成。
如果接口出现异常,FastAPI默认会在浏览器页面返回对话失败的JSON错误信息,方便定位是Key问题、模型名问题,还是TTS问题。命令行窗口也会打印“TTS失败”等日志,这些信息对排查很有帮助。
6. 常见问题与排查思路
6.1 LLM接口调用报错
现象是POST /api/chat返回500,FastAPI日志里出现类似“对话失败”的字段,并附带401、404或超时信息。常见原因有几个:API Key填写错误、base_url路径不对、模型名不存在,或者网络无法访问模型服务商。
排查时,先用curl或API服务商的测试页面直接验证接口连通性。比如确认你用的模型名称是服务商文档里的真实值,确认base_url是完整以/v1结尾的地址。如果确认无误依然报错,用浏览器直接访问你填的base_url,看是否能正常返回说明页。也有一种隐蔽情况:服务商新模型名称与老SDK默认版本不兼容,这时可以升级openai包,或改用该服务商推荐的SDK。
6.2 TTS无声或生成失败
现象是页面文字正常,但没有语音条,或语音条加载后播放无声。原因主要有三个:部署机器无法访问edge-tts所在服务的接口;TTS_VOICE配置的语音名不存在;在FastAPI异步接口中直接调用了asyncio.run,导致事件循环冲突。
排查时,可以先单独写一个临时Python脚本调用edge_tts生成mp3,确认网络和音色是否正常。如果网络受限,换用本地TTS方案。如果遇到asyncio.run报错,把FastAPI接口从async def改成普通def即可,本文的main.py已经采用了普通def定义。若语音生成成功但播放无声,检查audio元素是否设置了controls属性,以及音频路径是否能在浏览器中直接访问。
6.3 角色人设崩塌或回复生硬
当你发现海屿聊了几轮后开始像通用助手,说“作为AI,我不能……”这类话,或者回复越来越机械,这就是人设崩塌。最常见的原因是System Prompt不够具体,或者历史消息过长导致模型把需要遵守的角色规则给“挤”了出去。
解决思路是:把角色卡写得更具体,增加说话风格示例;temperature不要超过0.8;每次请求都带上完整的System Prompt;同时限制历史消息轮数,比如只保留最近10到12轮,避免token过长。你还可以给角色卡增加few-shot示例,也就是一小段“用户问X,海屿答Y”的样例对话,让模型模仿得更稳定。
6.4 请求越聊越慢、成本越聊越高
这是多人上线后几乎一定会遇到的情况:聊天轮次变多,前端把整个history发给后端,后端又把所有历史消息拼进大模型请求,导致输入token越来越多,单次响应耗时和成本都上升。
解决方法是做上下文管理。最基础的做法是只保留最近N轮历史;进阶做法是给历史做摘要,比如每5轮生成一句总结,再配合最近对话一起发送;再进一步可以引入向量数据库,把用户常聊的话题和记忆点检索出来拼进Prompt。这些方案各有取舍,需要根据产品形态决定。
| 问题现象 | 常见原因 | 解决思路 |
|---|---|---|
| 接口返回500,提示对话失败 | API Key错误、base_url不对、模型名不存在 | 先用curl验证接口,再检查.env配置 |
| 页面无语音条 | edge-tts网络不通、语音名错误、事件循环冲突 | 单独脚本测试TTS,接口改为普通def |
| 角色人设崩塌 | Prompt不具体、历史过长、温度过高 | 加强角色卡、加入示例、限制历史轮数 |
| 聊天越来越慢 | 历史消息全部发送,token膨胀 | 只保留最近N轮,或对早期消息做摘要 |
7. 最佳实践与工程建议
7.1 内容安全与角色边界
AI虚拟角色陪伴应用如果上线面向公众,内容安全是绝对不容妥协的底线。角色设定必须避免诱导未成年人提及儿童相关内容,要坚决隔离色情、暴力、自伤等不良引导。角色卡中应明确写入“禁止输出涉黄、涉暴、涉未成年人不良内容”,并在碰到违规话题时温和转移话题。这既是对用户的保护,也是开发者自身合规的要求。
不要相信所谓“无审核、无限制”的AI角色产品方案。真正合规的产品,应该在系统Prompt层加入安全约束,在模型输入输出侧接入内容审核服务,甚至在业务入口增加敏感词过滤。聊天记录如果涉及用户隐私,还要在隐私政策中明确告知用户,并保证数据不用于未经授权的模型训练。权限方面,生产环境建议按用户维度隔离上下文,不要让用户A读到用户B的聊天记录。
7.2 Prompt稳定性设计
角色卡的System Prompt是产品体验的命脉,建议把它作为工程资产看待。角色数据用结构化配置存放,方便做版本管理;每条Prompt加上版本号,便于线上对比和回滚。如果团队协作,可以在专门的配置文件或配置中心里维护角色卡,只有受控的成员可以修改。
测试Prompt时,不要只测一两句话,要准备一套包含开心、低落、生气、闲聊、违规试探等场景的回归用例,每次修改后都跑一遍,确认没有改变角色性格基线。这种“Prompt回归测试”看似重,但对体验稳定很有价值。
7.3 成本与性能优化
对接大模型时,成本控制可以从几个角度入手。第一是模型分级:简单寒暄和情绪支持用便宜的小模型,复杂角色剧情再用大模型,通过规则或网关做路由。第二是TTS音频缓存:相同回复文本不要重复合成,用文本哈希作为缓存key,存储复用。第三是文件管理:本文的语音文件用uuid命名且没有自动清理,生产环境需要定时清理或使用对象存储,避免磁盘吃满。
并发方面,当前Demo的单线程同步接口在压力下会比较吃力。可以改用异步任务队列,把TTS这类耗时操作丢到后台线程执行,或直接接入消息队列让语音合成异步化。接口层也要配置超时和重试,避免上游模型服务抖动导致整体故障。
7.4 记忆扩展:从内存到存储
本文用history数组实现的是页面级记忆,关闭浏览器就丢失,显然不够生产级。比较通用的方案是:短期对话记忆放Redis,以用户ID为key保存最近N轮消息;长期记忆放向量数据库,定期把用户喜好、重要事件、角色对用户说过的话向量化存储,在构造Prompt时把相似记忆检索出来追加进去。
这样角色才能真正“记住”你。比如海屿如果记得你最喜欢海盐拿铁,下次聊到甜品时她就能主动提起。这类记忆工程也是AI Agent产品的基础能力,值得单独研究。
7.5 从Demo走向生产清单
把一个本地Demo变成一个可交付产品,除了前面说的记忆、缓存、安全,还至少需要做这些事:用户登录与身份识别;内容审核服务接入;日志和监控,至少记录每次请求的消息量、耗时、敏感词命中情况;部署到云服务器或容器平台后,配置域名和HTTPS;对接口做压测,确认单实例能承受的并发;建立Prompt和角色卡的发布流程,支持灰度发布和紧急回滚。
这些工作不会让角色变得更有演技,但它们是产品能不能活下来、能不能上线的关键。如果只是个人项目或学习Demo,做到本文这个程度其实已经足够完整,大可继续往角色内容方向深耕。
8. 总结与学习路线
到这里,你已经完成了“AI海屿”这个夏末海边主题虚拟角色的从零搭建,核心链路包括:用角色卡约束大模型人设、封装LLM对话接口、用情感词典判断用户情绪、用edge-tts把回复转成语音,再到前端展示并联动背景音乐。整个过程没有依赖私有框架,全部基于通用开源组件,代码可以直接复制扩展。
如果继续深入学习,建议按三条路线走。第一条是对话工程,学习LangChain或LlamaIndex中的记忆模块、摘要策略和Prompt模板管理。第二条是语音能力,了解本地语音合成和声音克隆方案,以及如何给不同情绪选择不同音色。第三条是Agent化,把工具调用引入角色互动,让海屿真正能帮你查天气、推荐海边路线,这时你已经进入AI Agent工程领域,可以研究Multi-Agent协作、模型路由和工具调度。
最后分享一个做角色项目的经验:最容易出效果的不在于堆功能,而在于把人设写细。一个能说出“今天的风像刚从冰箱拿出来的汽水一样清爽”的角色,比一个全知全能的助手更能打动用户。你可以先复制本文代码跑通,然后从自己的成长经历、喜欢的地点、珍藏的片段入手,塑造一个真正“只有你知道”的角色。也欢迎在评论区分享你调出的海屿是什么样的。
