Lanlan（兰兰）是一个新手友好、开箱即用的，具有听觉、视觉、工具调用和多端同步功能的AI猫娘伙伴。本项目有三个核心目标：

1. 极致的低延迟。本项目的用户界面以语音交互为主，一切系统级设计皆须优先确保降低语音延迟，且任何服务不得阻塞对话进程。

2. 全场景同步。猫娘可以在手机、电脑和智能眼镜上同时存在，且同一只猫娘在不同终端同时存在时，行为应当完全同步。 (假想场景：如果家中有多个显示器，每一个显示器上都放置着猫娘，那么我们希望无论走到哪里都是在跟同一只猫娘对话，实现全方位环绕式体验。)

3. 轻量化。每一项技术的引入都必须提升实际的用户体验，避免增加不必要的插件和选项。

后端以Python为主，以实时多模态API为主要处理器，搭配多个基于文本的插件模组。前端以H5+JS为主，通过Electron和PWA转换为App。

1. 获取阿里云API。在阿里云的百炼平台官网注册账号。新用户实名认证后可以获取大量免费额度，记得留意页面上的"新人福利"广告。注册完成后，请访问控制台获取API Key。一键包用户可以通过设置页里的按钮设置API Key，开发者也可以直接修改config/api.py里的内容（首次配置请参考config/api_template.py）。

   注：本项目提供的都是官方链接，不含任何推广，本人无法从中获取任何收益。阿里的官网目前做的很烂，请忍耐orz

2. 体验网页版。对于一键包用户，直接运行启动网页版.bat即可打开网页版。请耐心等待网页刷新，并先根据提示配置API Key。

3. 体验桌宠模式。如果网页版可以正常使用，一键包用户可以考虑继续通过启动App版.bat开启桌宠模式。注意，请不要同时使用网页版和App版。请确认exe文件没有被系统或杀毒软件隔离。 使用结束后请在桌面右下角找到小八图标，右键退出，并手动关闭终端。

对于开发者，请在克隆本项目后，(1)新建pyhon3.12环境。(2)执行pip install -r requirements.txt安装依赖。(3)复制config/api_template.py到config/api.py并进行必要配置。(4)执行python memory_server.py和python main_server.py。(5)通过main server中指定的端口（默认为http://localhost:48911）访问网页版。

• 网页版访问http://localhost:48911/chara_manager即可进入人设编辑页面。初始 猫娘 伙伴的预设名称为test，建议直接修改名字，并一项一项添加或修改基础人设，但尽量控制数量。

• 进阶人设主要包括Live2D模型设置(live2d)和声音设置(voice_id)。如果你想要更改Live2D模型，请先将模型目录复制到本项目中的static文件夹下。从进阶设置中可以进入Live2D模型管理界面，可以更换模型，并通过拖拽和鼠标滚轮调整模型的位置和大小。如果你想要更改角色声音，请准备一段15秒左右的连贯、干净的语音录音。通过进阶设置进入语音设置页面，上传录音即可完成自定义语音。

• 进阶人设中还有一个system_prompt，可以对系统指令进行完全自定义，但不建议修改。

本项目环境依赖非常简单，请在python3.12环境中执行pip install -r requirements.txt即可。请注意将config/api_template.py复制为config/api.py.开发者建议加入企鹅群1048307485，猫娘名称见项目标题。

1. 添加前端UI用于记忆管理（记忆检索和纠错）。

2. 支持L2D表情控制和动作控制。

3. 兼容工具调用或MCP（本质是工具调用，不强求兼容MCP）。

1. 猫娘网络。允许猫娘之间自行通信。需要一定的用户量基础，因此优先级下调。

2. 针对手机端的优化。将会话管理器后端迁移至JS，直接与API服务器端通信；只将记忆服务器保存在PC端，则可以降低手机端延迟。但是，这与本项目的"多端同步"的主目标不一致，因此优先级下调。

3. 将Memory Server改造成MCP服务器，以MCP的形式让同一个猫娘兼容不同语言模型、聊天框架。（工作量不是很大）

1. 通过图片注释的方式使非视觉模型也能看到屏幕。既然已经有全模态模型，个人认为这部分工作应该交由API服务商去解决，因此优先级极低。

2. 接入QQ等聊天工具。由于语音模型是实时特化的，接入QQ本质上只有记忆部分可以共享，核心API需要更换为文本模型。工作量较大，且重复造轮子的部分很多。不如将Memory Server改造成MCP服务器后直接接入其他聊天AI框架。

你为什么要用阿里？为什么不用Deepseek？

因为阿里是全模态模型，它说话快。

你为什么要用8B模型？你不知道8B模型都是笨比吗？

因为阿里目前只有8B模型，它说话快。

能不能换别的厂家/离线运行/换别的模型/xxx试试？

对不起，但是它说话快。

为什么我的AI感觉笨笨的？

本项目无法对AI的智能水平负责，只能帮助您选择当前综合性能最优的解决方案。如果您已经看过本项目在Bilibili的视频，那么直播版与开源版代码逻辑一致，只有支持的API接口不一致。有条件者可以将config/api.py中的CORE_URL/CORE_API_KEY/CORE_MODEL替换成OpenAI的GPT-4o版本，即可将模型从Qwen升级为GPT-4o。也可以等待阿里或其他国内厂家的升级与跟进。

技术的进步不在一朝一夕，请耐心守候AI的成长！

Live2D模型的嘴巴怎么张不开？

本项目已经兼容了L2D模型的全部两种口型同步方式。口型同步出现问题，大概率是Live2D模型本身不支持，而不是本项目的问题。

是否支持MCP服务、工具、插件？

OpenAI官方的Realtime API支持tool calling功能，因此，本项目与MCP服务兼容，且直播版已经实装了联网搜索等工具。但是，与常规文本模型不同的是，实时模型使用工具需要考虑异步协同和阻塞问题。此外，目前阿里平台并不支持工具调用。因此，开源项目暂时没有MCP兼容性的计划，留待国内厂商实现相关接口后再跟进。

本项目支持哪些语言模型？

本项目依赖于实时全模态API。直播版本使用的是Gemini Live API，开源版本使用的是OpenAI Realtime API。Gemini Live具有更好的效果，但目前只支持谷歌。OpenAI Realtime目前有OpenAI和阿里云两家服务商支持，未来可能兼容更多模型。开源版只支持Qwen-Omni-Realtime和GPT-4o-Realtime两个模型。

为什么xxx项目的语音对话延迟比你还低？

影响对话延迟的因素有：

• 上下文长度：主要因素。冗长的人设文本和记忆池，会导致对话延迟的显著上升。
• 模型大小：主要因素。越大的模型越智能，需要在智能与延迟之间权衡。本项目使用的模型中，Qwen-Omni是目前8B级别模型中最强的，GPT-4o则有30B级别的激活参数。小于8B的模型可能取得更低的响应延迟，但也会相应地变笨。注意，影响延迟的只有MoE中的激活参数量。
• 缓存命中率：当输入的前缀不变时，能够有效命中语言模型的KV缓存，从而显著降低延迟。因此，尽量使用增量式插入，而不要频繁修改先前（尤其是开头）的对话。
• 网络延迟：通常在200ms以内，并不是影响延迟的主要因素。但如果存在网络波动，可能会导致语音卡顿。

如果你确实有发现相同上下文长度、相同智能水平下，延迟更低的解决方案，请提交issue，感谢分享。

你这项目的标题到底是个什么玩意儿？

Chat酱是本人2023年3月制作的基于Chatgpt的QQ聊天猫娘。兰兰是2024年3月制作的基于GPT4v和Discord的语音+视觉多模态AI猫娘。小八是本人于2025年4月制作的全场景AI猫娘。标题承载了本人三年间的心路历程。现在姑且还是叫Project Lanlan吧？

为什么要设计xxx/xxx/xxx？

建议进群私聊。很多目前看来冗余的设计，在直播版本（前瞻版本）中都有更多用处。

特别感谢明天好像没什么、喵和小韭菜饺协助测试。特别感谢大毛怪灬嘎提供的logo素材。