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

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

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

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

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

1. 对于一键包用户，直接运行新版启动器.exe即可打开主控面板。

2. 启动调试模式。初次使用请务必选择启动器最下方的启动调试模式。 请耐心等待网页刷新，并先根据提示配置API Key。

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

以上。

使用过程中你需要配置一个第三方AI服务。本项目目前推荐使用 阿里云 或 智谱。一键包用户可以通过设置页里的按钮设置API Key，开发者也可以直接修改config/api.py里的内容（首次配置请参考config/api_template.py）。

获取 阿里云API。在阿里云的百炼平台官网注册账号。新用户实名认证后可以获取大量免费额度，记得留意页面上的"新人福利"广告。注册完成后，请访问控制台获取API Key。

获取 智谱API。在智谱开放平台官网注册账号并充值1元后，可以领取大量免费额度。登陆成功后，请从API 控制台获取API Key。

对于开发者，请在克隆本项目后，(1)新建pyhon3.11环境。(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即可进入人设编辑页面。初始 猫娘 伙伴的预设名称为小天，建议直接修改名字，并一项一项添加或修改基础人设，但尽量控制数量。

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

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

• 通过访问http://localhost:48911/api_key可以切换核心API和辅助API（记忆/语音）的服务提供商。Qwen功能全面，GLM完全免费。

• 通过访问http://localhost:48911/memory_browser可以浏览和校对近期记忆与摘要，一定程度上缓解模型复读、认知错误等问题。

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

开发者详细启动步骤如下：(1)新建pyhon3.11环境。(2)执行pip install -r requirements.txt或uv sync安装依赖。(3)复制config/api_template.py到config/api.py并进行必要配置。(4)执行python memory_server.py, python main_server.py(可选python agent_server.py)。(5)通过main server中指定的端口（默认为http://localhost:48911）访问网页版。

项目架构

Lanlan/
├── 📁 brain/                    # 🧠 背景Agent模块，根据前端对话内容，控制键鼠和MCP
├── 📁 config/                   # ⚙️ 配置管理模块
│   ├── api.py                   # API密钥配置
│   ├── prompts_chara.py         # 角色提示词
│   └── prompts_sys.py           # 系统提示词
├── 📁 main_helper/              # 🔧 核心模块
│   ├── core.py                  # 核心对话模块
│   ├── cross_server.py         # 跨服务器通信
│   └── omni_realtime_client.py  # 实时API客户端
├── 📁 memory/                   # 🧠 记忆管理系统
│   ├── store/                   # 记忆数据存储
├── 📁 static/                   # 🌐 前端静态资源
├── 📁 templates/                # 📄 前端HTML模板
├── 📁 utils/                    # 🛠️ 工具模块
├── 📁 launcher/                 # 🚀 Rust启动器
├── main_server.py               # 🌐 主服务器
├── agent_server.py              # 🤖 AI智能体服务器
└── memory_server.py             # 🧠 记忆服务器

数据流向

1. 移除memory server中语义索引的部分，引入Graphiti用于长期记忆存储；开放settings update功能。

2. 用React对前端进行重构，筹备手机端独立运行版本。

3. 支持文本输入功能。

1. 通过引入Unity支持3D模型。

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

3. 接入QQ/cursor等外部软件。由于语音模型是实时特化的，cursor类软件只能以工具形式被Lanlan调用；QQ类软件只能将Memory Server嵌入到其他框架。

4. 完善原生工具调用。

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

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

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

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

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

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

OpenAI官方的Realtime API支持tool calling功能，因此，本项目与MCP服务兼容，且直播版已经实装了联网搜索等工具。但是，与常规文本模型不同的是，实时模型使用工具需要考虑异步协同和阻塞问题。此外，目前阿里平台并不支持工具调用。

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

本项目依赖于实时全模态API。直播版本使用的是Gemini Live API，开源版本使用的是OpenAI Realtime API。Gemini Live接口具有更好的效果，但目前只支持谷歌。OpenAI Realtime接口规范目前有OpenAI，阿里云，智谱，阶跃星辰 四家服务商支持，未来可能兼容更多模型。开源版支持Step-Audio,Qwen-Omni-Realtime,GLM-Realtime和GPT-Realtime四个模型。

已知其他支持实时模式但不兼容OpenAI Realtime的模型：(字节跳动)豆包实时语音交互，(商汤)SenseNova V6 Omni，(科大讯飞)星火认知超拟人

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

影响对话延迟的因素有：

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

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

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

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

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