跳到主要内容
Kirara AI 开源多模型多平台 AI 机器人框架架构与实现解析 | 极客日志
Python SaaS WeChat AI
Kirara AI 开源多模型多平台 AI 机器人框架架构与实现解析 深度解析 Kirara AI 开源框架,旨在解决 AI 能力与用户触点连接及多渠道部署复杂性问题。框架采用适配器模式解耦 LLM 与聊天平台,支持数十种模型热切换及 QQ、微信等多平台统一接入。核心架构包含依赖注入容器、事件驱动异步通信、工作流 DAG 引擎及记忆系统。通过模块化设计降低定制门槛,节省重复开发成本,适合中高级开发者快速集成 AI 对话能力。
鲜活 发布于 2026/4/5 更新于 2026/5/24 38 浏览Kirara AI:一个开源多模型、多平台 AI 机器人框架的架构与实现深度解析
1. 整体介绍
1.1 项目概要
Kirara AI 是一个开源的、旨在整合主流大语言模型(LLM)与主流聊天平台的一体化机器人框架。项目地址为 https://github.com/lss233/kirara-ai。从项目徽章看,其在 GitHub 上获得了相当的关注度(Stars),并通过 PyPI 分发,拥有持续集成(CI/CD)和代码覆盖率检查,表明项目具备一定的工程成熟度。
1.2 主要功能与场景
核心价值 :解决'AI 能力'与'用户触点'之间的连接与编排问题。
产品视角 :用户可通过一个系统,快速在 QQ、Telegram、微信等平台部署一个具备对话、绘图、语音等多模态能力的智能助手,并能通过图形化界面(WebUI)自定义其行为(工作流)和人格(预设)。
技术视角 :提供了一个可插拔的架构,将 LLM 调用、平台协议适配、业务逻辑(插件/工作流)进行解耦和标准化。
面临问题与对应场景 :
模型锁定的风险与成本问题 :企业和开发者不希望绑定单一 AI 服务商。
Kirara 的解决 :支持数十种国内外模型(OpenAI、Claude、DeepSeek、豆包等),可配置、可热切换,提供了模型无关的抽象层。
多渠道部署的复杂性 :为每个平台(QQ、微信、Telegram)单独开发机器人,重复工作量大,维护成本高。
Kirara 的解决 :统一的消息处理核心,搭配针对各平台协议的适配器(IMAdapter),实现'一次开发,多处部署'。
功能扩展与业务集成困难 :单纯的对话机器人无法满足复杂场景(如查询数据、触发自动化任务)。
Kirara 的解决 :通过插件系统和工作流引擎,允许以代码(插件)或可视化(工作流)方式编排复杂业务逻辑,并与记忆系统、外部服务(MCP)集成。
与传统方式的对比 :
传统方式 :为每个'平台 + 模型 + 功能'组合单独开发项目,形成'烟囱式'架构。代码复用率低,变更波及范围大。
Kirara 新方式 :采用'核心总线 + 标准化适配器'架构。核心负责会话、调度、记忆等通用能力;适配器负责与具体平台或模型对接。新增平台或模型只需实现对应适配器,无需改动核心业务逻辑。工作流系统进一步将业务逻辑可视化、模块化,降低定制门槛。
商业价值估算逻辑 :
估算一个具备类似多模型、多平台、插件化、工作流及 Web 管理后台的框架从零开始的开发成本。
成本项 :核心架构设计、各平台协议逆向/封装、各模型 API 适配、插件体系、工作流引擎、Web 前端、文档等。
保守人月估算 :15-25 人月(高级全栈团队)。
覆盖问题空间 :解决了中小型团队/个人在 AI 机器人领域从'想法'到'多平台部署'的绝大部分基础工程问题。
效益估算 :作为开源项目,其价值体现在为整个社区节省的重复开发成本。假设有 100 个团队/个人使用,其累计节省的开发成本可能达到上千人月,商业潜力体现在基于其快速交付定制化解决方案的能力上。
2. 详细功能拆解(产品 + 技术视角)
产品功能模块 对应的核心技术组件 技术设计要点 多模型'大脑' LLMManager, LLMBackendRegistry,
LLMBackendAdapter
适配器模式 :每个模型后端实现统一的 LLMBackendAdapter 接口。工厂模式 :通过 LLMBackendRegistry 注册和实例化适配器。负载均衡 :支持为同一模型配置多个后端实例并随机选择。
多平台'连接器' IMManager, IMRegistry, IMAdapter适配器模式 :每个聊天平台实现统一的 IMAdapter 接口,负责消息收发。生命周期管理 :IMManager 统一管理所有适配器的启动、停止和状态。
可扩展的'身体' PluginLoader, Plugin 基类,BlockRegistry依赖注入(DI) :插件通过 @Inject 获取核心服务。事件驱动 :插件可监听 EventBus 上的各类事件。模块化 :工作流中的功能单元抽象为 Block,可在插件中注册新类型。
智能'中枢神经' WorkflowDispatcher, WorkflowExecutor, Workflow有向无环图(DAG)引擎 :Workflow 由 Block 和 Wire 构成执行图。异步执行 :WorkflowExecutor 负责图的拓扑排序与异步调度执行。条件与循环 :内置 ConditionBlock 和 LoopBlock 实现复杂逻辑。
长期'记忆' MemoryManager, MemoryScope, MemoryEntry作用域隔离 :记忆按 MemberScope(用户)、GroupScope(群组)等维度存储和查询。媒体引用 :通过 MediaCarrierService 管理消息中媒体文件的生命周期,避免重复存储。可插拔持久化 :支持文件、Redis 等多种存储后端。
统一'管控面' WebServer (FastAPI), WebUI 前端前后端分离 :后端提供 RESTful API,前端为独立的 React/Vue 项目。配置集中管理 :所有配置可通过 WebUI 动态修改并持久化。
3. 技术难点与核心因子
依赖注入(DI)容器的设计与集成 (DependencyContainer):如何优雅地管理 LLMManager、IMManager、插件等众多组件及其依赖关系,是实现松耦合架构的关键。
事件驱动的异步通信 (EventBus):在高并发的聊天消息处理场景下,如何确保消息、插件、工作流之间高效、解耦的通信。
工作流引擎的健壮性 (WorkflowExecutor):如何正确解析和执行包含并行、条件分支、循环的 DAG,并处理节点执行失败、超时等问题。
跨平台消息的抽象 (ChatSender, ChatMessage):设计一个足够通用且可扩展的数据结构,来承载 QQ、Telegram、微信等平台各异的消息类型(文本、图片、语音、引用等)。
多模型负载均衡与降级 (LLMManager.get_llm):当一个模型对应多个后端时,如何制定选择策略(随机、轮询、基于延迟);在后端失效时如何无缝降级。
记忆系统的媒体引用管理 (MediaCarrierService):解决'一条记忆引用一张图片,该图片被多个记忆引用'的复杂所有权问题,防止媒体文件被误删。
4. 详细设计图
4.1 核心架构图 [图 1:Kirara AI 高层架构图。展示了从平台消息接入,经过核心调度器(事件总线、工作流分发),最终调用具体能力后端(LLM、绘图、记忆)的完整流程,以及配置与数据的管理。]
4.2 核心链路序列图(消息处理) MemoryManager -> LLM Backend -> LLMManager -> WorkflowExecutor -> WorkflowDispatcher -> EventBus -> IMAdapter -> Platform (e.g., QQ)
用户发送消息 -> 发布 MessageReceived 事件 -> 触发调度规则匹配 -> 执行匹配到的工作流 -> query () 获取历史记忆 -> get_llm () 获取模型实例 -> 调用 generate () 返回回复文本 -> store () 存储本轮记忆 -> 调用 send () 方法向用户回复消息
图 2:一条用户消息触发 AI 回复的核心处理序列。体现了事件驱动、工作流执行、记忆查询与存储、LLM 调用等关键环节的交互。
4.3 核心类图(简略) IMManager
+adapters: Dict[str, IMAdapter]
+start_adapters(loop)
+stop_adapters(loop)
+create_adapter(name, class, config)
«abstract»
IMAdapter
+is_running: bool
+start()
+stop()
+send(message)
LLMManager
+active_backends: Dict[str, List[LLMBackendAdapter]]
+load_backend(name)
+unload_backend(name)
+get_llm(model_id)
«abstract»
LLMBackendAdapter
+backend_name: str
+generate(messages)
Workflow
+name: str
+blocks: List[Block]
+wires: List[Wire]
WorkflowExecutor
+workflow: Workflow
+run(): Dict[str, Any]
-_execute_nodes()
-_can_execute(block)
MemoryManager
+persistence: MemoryPersistence
+store(scope, entry)
+query(scope, sender)
+shutdown()
DependencyContainer
+register(type, instance)
+resolve(type)
+scoped(): ContextManager
Block
Wire
图 3:核心类关系图。展示了管理器类与适配器类的聚合关系、工作流相关类的组合关系,以及 DI 容器的中心地位。
4.4 工作流执行函数拆解图 (WorkflowExecutor._execute_nodes) [图 4:WorkflowExecutor._execute_nodes 方法的核心逻辑流程图。展示了其如何根据 Block 类型进行分支处理,并递归执行后续节点。]
5. 核心函数与代码解析
5.1 依赖注入与组件初始化 (entry.py - init_application) 这是整个应用的启动入口,清晰地展示了基于依赖注入容器的组装过程。
def init_application () -> DependencyContainer:
"""初始化应用程序:装配所有核心组件。"""
container = init_container()
container.register(GlobalConfig, config)
db = DatabaseManager(container)
container.register(DatabaseManager, db)
container.register(IMRegistry, IMRegistry())
container.register(LLMBackendRegistry, LLMBackendRegistry())
im_manager = IMManager(container)
container.register(IMManager, im_manager)
llm_manager = LLMManager(container)
container.register(LLMManager, llm_manager)
llm_manager.load_config()
plugin_loader.discover_internal_plugins()
plugin_loader.load_plugins()
return container
解析 :该函数是'组合根'的体现。它控制着整个应用的组装流程,将所有松散耦合的组件(配置、管理器、适配器、插件)通过 DependencyContainer 连接成一个完整的应用。这种模式极大提高了可测试性和可维护性。
5.2 LLM 后端管理 (llm_manager.py - LLMManager.load_backend) def load_backend (self, backend_name: str ):
"""加载指定的后端:动态创建适配器并注册到模型映射中。"""
backend_config = next ((b for b in self .config.llms.api_backends if b.name == backend_name), None )
if not backend_config or not backend_config.enable:
raise ValueError(...)
adapter_class = self .backend_registry.get(backend_config.adapter)
config_class = self .backend_registry.get_config_class(backend_config.adapter)
with self .container.scoped() as scoped_container:
scoped_container.register(config_class, config_class(**backend_config.config))
adapter = Inject(scoped_container).create(adapter_class)()
adapter.backend_name = backend_name
self .backends[backend_name] = adapter
for model_config in backend_config.models:
model_id = model_config.id
self .model_info[model_id] = model_config
if model_id not in self .active_backends:
self .active_backends[model_id] = []
self .active_backends[model_id].append(adapter)
self .event_bus.post(LLMAdapterLoaded(adapter=adapter, backend_name=backend_name))
解析 :这是抽象工厂模式 和依赖注入 的经典结合。通过注册表解耦了配置中的字符串(如 adapter: "openai")与具体的适配器类。使用 scoped_container 确保每个适配器实例拥有自己独立的配置实例。最终建立的 active_backends 字典是实现多模型支持 和负载均衡 (通过 get_llm 随机选择)的数据结构基础。
5.3 工作流节点执行 (workflow/core/execution/executor.py - _execute_nodes) async def _execute_nodes (self, blocks: List [Block], executor, loop ):
"""执行一组节点,处理条件、循环和普通块的分发。"""
for block in blocks:
if isinstance (block, ConditionBlock):
await self ._execute_conditional_branch(block, executor, loop)
elif isinstance (block, LoopBlock):
await self ._execute_loop(block, executor, loop)
else :
await self ._execute_normal_block(block, executor, loop)
async def _execute_normal_block (self, block: Block, executor, loop ):
"""执行普通块:检查依赖,收集输入,运行,传播结果。"""
if self ._can_execute(block):
inputs = self ._gather_inputs(block)
future = loop.run_in_executor(executor, functools.partial(block.execute, **inputs))
try :
result = await future
self .results[block.name] = result
next_blocks = self .execution_graph[block]
if next_blocks:
await self ._execute_nodes(next_blocks, executor, loop)
except Exception as e:
raise BlockExecutionFailedException(...) from e
解析 :_execute_nodes 是策略模式 的体现,将不同类型的 Block 执行逻辑分离。_execute_normal_block 展示了 DAG 引擎的关键:
依赖检查 (_can_execute):确保一个节点的所有输入就绪。
数据传递 (_gather_inputs):通过 self.results 字典和 wires 定义的连接关系,将上游输出传递给下游输入。
异步执行 :使用 run_in_executor 处理可能阻塞的 block.execute 调用。
递归传播 :一个节点执行完成后,立即触发其后继节点的执行检查,实现数据驱动 的推进。
5.4 总结 Kirara AI 成功构建了一个模块化、可扩展、生产就绪 的 AI 机器人框架。其技术选型与架构设计(依赖注入、事件驱动、适配器模式、工作流 DAG)贴合了现代复杂软件系统的要求。通过将'模型'、'平台'、'功能'三个维度抽象为可插拔的适配器,它有效地应对了 AI 应用落地中的多样性和变化性挑战。对于希望在自有场景中快速集成 AI 对话能力的中高级开发者而言,研究和借鉴其架构设计,比从头造轮子更具效率和价值。其核心代码展示了良好的抽象能力和工程实践,是开源社区中一个值得深入学习的优秀项目。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
随机西班牙地址生成器 随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online
curl 转代码 解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online