1. 项目概述一个面向开发者的AI应用快速构建框架最近在折腾AI应用开发的朋友应该都体会过那种“从想法到原型”的中间环节有多磨人。你想做一个能联网搜索的智能客服或者一个能处理多格式文档的问答助手光是搭建基础环境、处理API调用、设计对话流、管理上下文就得花上好几天。更别提还要考虑前后端分离、状态管理、插件扩展这些工程化问题了。很多时候一个创意还没开始验证热情就先被繁琐的基建消耗殆尽了。lss233/kirara-ai这个项目就是为了解决这个痛点而生的。你可以把它理解为一个“AI应用的全栈脚手架”或者“AI领域的Next.js”。它的核心目标是让开发者尤其是全栈或后端开发者能够以极低的成本和极高的效率构建出功能完整、可扩展的生产级AI应用。它不是另一个聊天界面皮肤也不是简单的API封装而是一套包含了前端界面、后端服务、插件系统、工具调用、知识库集成等完整能力的开源框架。简单来说如果你厌倦了每次都要从零开始写OpenAI或Ollama的调用代码厌倦了手动拼接提示词和管理对话历史或者想快速集成Google Search、DALL-E画图、GitHub操作等能力到你的AI助手里面那么kirara-ai值得你花时间了解一下。它把那些重复的、通用的脏活累活都封装好了你只需要关注最核心的业务逻辑和创意实现。2. 核心架构与设计哲学拆解2.1 为什么是“全栈”框架市面上AI相关的开源项目很多但大致可以分为几类纯前端的聊天UI如chatbot-ui、纯后端的SDK或中间件如LangChain、LlamaIndex、以及一些偏向运营的对话平台。kirara-ai的定位非常明确它要提供一个开箱即用的、完整的应用解决方案。这意味着当你克隆下这个项目经过简单的配置和启动你得到的不只是一个后端API服务而是一个可以直接在浏览器里访问、拥有完整聊天界面、支持多会话、具备文件上传、插件调用等功能的Web应用。它的架构天然是前后端一体的后端用Python的FastAPI构建提供健壮的API和插件运行时前端则是一个现代化的React单页应用提供了优秀的用户体验。这种设计极大地降低了全链路开发的复杂度。背后的设计哲学是“约定大于配置”和“电池内置”。框架已经为你做出了许多合理的默认选择比如使用SQLite作为默认数据库来存储会话和消息使用FastAPI来构建高性能API使用ReactViteTailwind CSS构建响应式前端。你不需要在这些基础设施上做决策可以直接开始编写你的AI逻辑。同时它内置了诸如身份验证虽然默认是关闭的、会话管理、消息持久化、流式响应等“电池”让你不必重复造轮子。2.2 核心概念会话、消息与工具要理解kirara-ai必须先理清它的几个核心数据模型这关系到你如何组织你的应用逻辑。会话Session这是最顶层的概念代表一次独立的对话上下文。例如用户和你聊“周末去哪玩”是一个会话切换到另一个话题“帮我写段代码”就可以开启另一个新会话。每个会话是隔离的拥有独立的对话历史和上下文窗口。框架会负责会话的创建、列表查询、删除和切换。消息Message消息是会话中的基本单元。每条消息都有明确的角色user用户、assistantAI助手、system系统或tool工具。一个完整的对话就是一系列按时间顺序排列的消息。框架的核心工作之一就是维护这个消息列表并在调用AI模型时将合适的历史消息作为上下文Prompt发送过去。工具Tool这是kirara-ai最强大的特性之一也是实现AI“行动力”的关键。工具本质上是一个可以被AI模型调用的函数。当用户在对话中说“今天北京的天气怎么样”时AI模型如果支持函数调用会分析出用户的意图是查询天气然后决定调用一个名为get_current_weather的工具并生成符合工具参数要求的调用请求如location: “北京”。后端收到这个请求后会实际执行对应的Python函数获取真实的天气数据再将结果以tool角色的消息插入对话历史最后让AI模型生成一段友好的回复给用户。kirara-ai的插件系统就是建立在“工具”这个概念之上的。一个插件可以提供一个或多个工具。框架内置了一些常用工具插件比如网络搜索、维基百科查询、画图等更重要的是它提供了极其简便的方式来创建你自己的自定义工具。3. 快速上手与核心配置详解3.1 环境准备与一键启动kirara-ai对运行环境的要求非常友好。由于它是一个Python后端项目你只需要确保系统中有Python 3.10和pip即可。官方推荐使用uv这个更快的Python包管理器和安装器但用传统的pip也完全没问题。第一步是获取代码。推荐使用git进行克隆这样可以方便地更新。git clone https://github.com/lss233/kirara-ai.git cd kirara-ai接下来是安装依赖。项目根目录下的pyproject.toml文件定义了所有依赖。使用pip安装是最直接的方式pip install -e .这里的-e参数代表“可编辑模式”安装这意味着你修改项目中的Python代码后无需重新安装更改会立即生效非常适合开发。安装完成后最关键的一步就是配置。项目根目录下有一个.env.example文件这是一个环境变量配置模板。你需要将其复制一份并重命名为.envcp .env.example .env然后用文本编辑器打开这个新创建的.env文件。这里面的配置项决定了你的AI应用将如何运行。3.2 核心环境变量配置解析.env文件里的配置项看起来可能有点多但大部分都有合理的默认值初期你只需要关注几个核心的。1. AI模型后端配置 (KIRARA_LLM_MODEL)这是最重要的配置决定了你的应用使用哪个AI模型。kirara-ai支持多种后端OpenAI 兼容 API: 这是最常用的方式。你需要将KIRARA_LLM_MODEL设置为类似openai:gpt-4o或openai:gpt-3.5-turbo的格式。同时你必须在.env中设置OPENAI_API_KEY和OPENAI_BASE_URL。OPENAI_BASE_URL允许你指向任何兼容OpenAI API格式的服务比如官方OpenAI、Azure OpenAI或者是你在本地或云端部署的Ollama、vLLM、LM Studio等。KIRARA_LLM_MODELopenai:gpt-4o OPENAI_API_KEYsk-your-openai-key-here # 如果你用本地Ollama可以这样配置 # OPENAI_BASE_URLhttp://localhost:11434/v1Ollama 本地模型: 如果你在本地运行了Ollama想使用llama3、qwen等本地模型配置更简单。将KIRARA_LLM_MODEL直接设置为Ollama中的模型名即可框架会自动识别。KIRARA_LLM_MODELllama3.2:latest # 确保Ollama服务正在运行其他模型: 框架还实验性支持Anthropic Claude、Google Gemini等具体配置可参考项目文档。注意模型名称中的前缀如openai:是适配器标识告诉框架使用哪种协议去调用。务必确保格式正确这是新手最容易出错的地方之一。2. 前端与后端服务配置KIRARA_WEB_HOST和KIRARA_WEB_PORT: 这定义了后端API服务器监听的地址和端口默认是127.0.0.1:8000。如果你想让同一网络下的其他设备也能访问可以改为0.0.0.0。KIRARA_FRONTEND_URL: 这是前端页面访问后端的地址。在开发时如果你前后端分开启动比如用npm run dev跑前端可能需要将其设置为前端的开发服务器地址如http://localhost:5173。如果使用默认的一体化启动方式这个配置通常不需要修改。3. 数据与存储配置KIRARA_DATABASE_URL: 数据库连接字符串。默认使用SQLite数据文件会保存在项目目录下的data/kirara.db。如果你希望使用PostgreSQL或MySQL可以修改这个连接字符串。KIRARA_DATA_DIR: 所有应用数据包括数据库、上传的文件、插件数据等的根目录默认为./data。配置好.env文件后就可以启动应用了。回到项目根目录运行kirara start这个命令会同时启动后端API服务器和前端Web服务。稍等片刻在浏览器中打开http://localhost:8000或你配置的端口就能看到kirara-ai的聊天界面了。第一次打开可能会让你设置一个用户名这只是本地标识并非强认证。4. 插件系统深度解析与自定义开发4.1 内置插件与启用机制kirara-ai的强大很大程度上体现在其插件生态上。插件就是功能的模块化封装。项目内置了一些非常实用的插件你可以在.env文件中通过KIRARA_PLUGINS变量来启用它们。例如如果你想启用网络搜索和画图功能可以这样配置KIRARA_PLUGINSsearch, dalle多个插件用英文逗号分隔。重启应用后你就能在聊天界面中看到新启用的功能。以search插件为例当你在对话中问“最近有什么科技新闻”时AI模型会尝试调用搜索工具后端则会使用配置的搜索引擎如SERPAPI或Google Search API去获取真实结果然后整合进回复中。每个插件都可能需要自己的配置。例如search插件可能需要SERPAPI_KEYdalle画图插件需要OPENAI_API_KEY或DALL-E专用的API Key。这些配置同样需要写在.env文件里。启用插件后务必查阅项目的plugins目录下对应插件的README或源码了解其必要的环境变量。4.2 从零开始编写一个自定义插件虽然内置插件很实用但kirara-ai真正的魅力在于可以轻松创建属于自己的插件将任何API或本地能力赋予AI。下面我们以创建一个“工作日计算器”插件为例演示完整流程。第一步创建插件目录结构在项目的plugins目录下如果没有则创建新建一个文件夹例如my_workday_calculator。在里面创建两个必需的文件__init__.py和plugin.toml。plugins/ └── my_workday_calculator/ ├── __init__.py └── plugin.toml第二步定义插件元信息 (plugin.toml)这个文件告诉kirara-ai你的插件叫什么、有什么能力。[plugin] name “工作日计算器” description “计算两个日期之间的工作日天数排除周末和自定义节假日。” version “0.1.0” author “Your Name” # 定义插件提供的工具列表 [[tools]] name “calculate_workdays” description “计算两个日期之间的工作日天数。需要提供开始日期和结束日期日期格式为 YYYY-MM-DD。” parameters [ { name “start_date”, type “string”, description “开始日期格式 YYYY-MM-DD”, required true }, { name “end_date”, type “string”, description “结束日期格式 YYYY-MM-DD”, required true }, { name “holidays”, type “array”, description “自定义节假日列表格式为 [‘YYYY-MM-DD’, …]”, required false } ]这里定义了一个名为calculate_workdays的工具它需要start_date和end_date两个必填参数以及一个可选的holidays数组参数。description字段非常重要AI模型特别是大语言模型会阅读这个描述来决定是否以及如何调用这个工具所以请用清晰、准确的语言描述工具的功能和参数。第三步实现工具逻辑 (__init__.py)这个文件是插件的核心包含了工具函数的实际代码。from datetime import datetime, timedelta from dateutil import parser from kirara.plugin import Plugin import logging logger logging.getLogger(__name__) class MyWorkdayCalculatorPlugin(Plugin): async def calculate_workdays(self, start_date: str, end_date: str, holidays: list None): “”” 计算两个日期之间的工作日天数。 “”” try: start parser.parse(start_date).date() end parser.parse(end_date).date() if start end: start, end end, start # 确保开始日期不晚于结束日期 # 将字符串格式的节假日转换为日期对象 holiday_dates set() if holidays: for h in holidays: try: holiday_dates.add(parser.parse(h).date()) except Exception as e: logger.warning(f“无效的节假日格式被忽略: {h}, 错误: {e}”) # 遍历计算 current start workday_count 0 while current end: # 判断是否为周末 (周一为0周日为6) if current.weekday() 5 and current not in holiday_dates: workday_count 1 current timedelta(days1) return { “start_date”: start.isoformat(), “end_date”: end.isoformat(), “total_days”: (end - start).days 1, “workdays”: workday_count, “holidays_considered”: list(sorted([h.isoformat() for h in holiday_dates])) if holiday_dates else [] } except Exception as e: logger.error(f“计算工作日时出错: {e}”, exc_infoTrue) return {“error”: f“日期计算失败: {str(e)}”} # 这个类方法用于向框架注册工具 classmethod def tools(cls): return [cls.calculate_workdays]代码解析插件类需要继承自kirara.plugin.Plugin。工具函数如calculate_workdays是一个普通的async方法。kirara-ai内部使用异步框架所以建议工具函数也定义为异步的特别是当你的工具需要执行网络I/O操作时。函数的参数名必须与plugin.toml中定义的parameters完全对应。函数应该返回一个可序列化为JSON的字典这个结果会被框架捕获并作为tool角色的消息插入对话。最后必须实现classmethod tools(cls)返回一个包含所有工具函数的列表。这是框架发现工具的钩子。第四步启用你的插件在.env文件中将你的插件名称添加到KIRARA_PLUGINS列表中KIRARA_PLUGINSsearch, my_workday_calculator重启kirara服务。现在你就可以在聊天窗口中对AI说“请帮我计算从2024-12-01到2024-12-31的工作日天数排除12月25号。” AI会理解你的意图调用你编写的工具并返回精确的计算结果。实操心得编写自定义插件时工具函数的description和参数描述是“人机沟通”的桥梁务必写得清晰、无歧义。返回的数据结构尽量规范便于AI模型理解和组织成自然语言回复。对于可能出错的网络请求或复杂计算一定要做好异常捕获和日志记录这在调试时至关重要。5. 高级特性与生产化部署考量5.1 上下文管理与优化策略随着对话轮数增加上下文长度会不断增长。所有消息都发送给AI模型不仅会导致响应变慢还可能因超过模型的令牌限制而失败。kirara-ai提供了灵活的上下文管理策略。默认情况下框架会保留整个会话的历史消息。但你可以在.env中通过KIRARA_MAX_HISTORY_MESSAGES来限制保留的消息条数例如设置为20则只保留最新的20条消息。更高级的策略是使用“摘要”或“向量化记忆”。虽然这不是kirara-ai的内置功能但你可以通过自定义插件来实现。例如可以编写一个插件在对话历史达到一定长度时触发一个工具调用使用AI模型将之前的冗长对话总结成一段简短的摘要然后用这个摘要替换掉旧的历史消息从而在保留核心信息的前提下大幅压缩上下文。这需要你对对话状态有更强的把控。5.2 文件上传与多模态处理kirara-ai支持文件上传功能。用户可以在前端界面上传图片、PDF、Word、TXT等文件。文件上传后后端会将其存储在配置的KIRARA_DATA_DIR目录下。如何处理这些文件内容取决于你的AI模型能力和插件。例如如果使用支持视觉识别的模型如GPT-4V你可以将图片的路径或base64编码放入上下文让模型“看到”图片。对于PDF、Word等文档你需要一个插件来提取其中的文本。这可以通过集成PyPDF2、python-docx或Unstructured等库来实现。插件提取文本后可以将文本内容作为系统消息或用户消息的一部分送入对话上下文从而实现基于文档的问答。框架本身负责文件的存储和基础管理而文件内容的解析和利用则给了开发者极大的自定义空间。5.3 部署到生产环境将kirara-ai用于个人项目和小团队内部工具直接运行kirara start可能就够了。但如果要对外提供服务就需要考虑生产化部署。1. 数据库升级默认的SQLite在并发写入时可能成为瓶颈。建议更换为PostgreSQL或MySQL。只需修改.env中的KIRARA_DATABASE_URL例如KIRARA_DATABASE_URL“postgresql://user:passwordlocalhost:5432/kirara_db”并确保已安装相应的数据库驱动如psycopg2。2. 反向代理与HTTPS使用Nginx或Caddy作为反向代理将kirara-ai的后端API默认端口8000和前端静态文件代理出去。同时配置SSL证书启用HTTPS这是生产环境的必备安全措施。3. 进程管理使用systemd、Supervisor或Docker来管理kirara进程确保其崩溃后能自动重启。kirara start命令启动的其实是Uvicorn服务器用于后端和前端静态服务。在生产环境你可能希望将它们分开管理或者使用Gunicorn配合Uvicorn工人进程来获得更好的并发性能。4. 身份验证与授权kirara-ai默认没有开启强制的用户认证这对于公开服务是危险的。你需要自行实现或集成认证层。一种方案是在Nginx层面配置HTTP Basic Auth或集成OAuth代理如oauth2-proxy。另一种更深入的方式是修改kirara-ai的后端代码在FastAPI应用中添加依赖项对需要保护的API路由进行JWT令牌验证。5. 容器化部署使用Docker和Docker Compose是最简洁的部署方式之一。你可以编写一个Dockerfile来构建包含所有依赖的镜像再用docker-compose.yml来定义服务应用、数据库等。这能保证环境的一致性极大简化部署流程。社区可能有现成的Docker配置可供参考。6. 常见问题与故障排查实录在实际使用和部署kirara-ai的过程中你可能会遇到一些典型问题。这里记录了几个我踩过的坑和解决方案。6.1 插件加载失败问题现象在.env中配置了插件但启动时日志报错Plugin ‘xxx’ not found或者前端看不到插件功能。排查步骤检查插件名称确保KIRARA_PLUGINS中的插件名称与插件目录名完全一致且目录位于项目的plugins/路径下。名称大小写敏感。检查插件结构确认插件目录下必须有__init__.py和plugin.toml两个文件且plugin.toml格式正确可以使用TOML在线校验工具。检查Python导入在__init__.py中确保插件类继承自kirara.plugin.Plugin并且类名与plugin.toml中的[plugin]部分没有直接关联但tools()类方法必须正确实现。可以尝试在项目根目录下打开Python交互环境手动from plugins.xxx import *看是否能成功导入。查看启动日志kirara start的启动日志会详细列出加载了哪些插件。如果插件有语法错误也会在这里显示。仔细阅读错误信息。6.2 AI模型无法调用或响应慢问题现象聊天界面显示发送失败或者等待响应时间极长。排查步骤确认模型配置首先检查.env中的KIRARA_LLM_MODEL和对应的API Key、Base URL是否正确。对于Ollama确认模型名正确且已通过ollama pull下载。测试API连通性如果是使用OpenAI兼容API可以用curl命令直接测试curl http://localhost:11434/v1/chat/completions \ -H “Content-Type: application/json” \ -H “Authorization: Bearer ollama” \ -d ‘{ “model”: “llama3.2”, “messages”: [{“role”: “user”, “content”: “Hello”}], “stream”: false }’将URL和model替换为你的配置。这能帮你确定问题是出在kirara-ai还是底层API服务。检查网络与代理如果你的环境需要通过代理访问外部API需要确保kirara-ai的进程能正确使用代理。可以在启动命令前设置环境变量如export HTTP_PROXYhttp://your-proxy:port。模型本身响应慢一些本地大模型或网络状况不佳时响应本身就很慢。可以尝试在前端发送一个简单问题观察后端日志中从发送请求到收到响应的耗时。6.3 文件上传后无法被AI处理问题现象文件可以成功上传但在对话中提及文件内容时AI似乎“看不到”文件。排查步骤确认文件存储路径检查.env中的KIRARA_DATA_DIR确认上传的文件确实存储在了该目录下的uploads子文件夹中。检查插件或上下文处理框架只负责存储文件不负责自动解析内容。你需要对于图片确认你使用的AI模型支持视觉识别如GPT-4V并且你的请求中正确包含了图片的引用例如通过插件将图片转换为base64编码并放入消息内容。对于文档你需要编写或启用一个文档处理插件。该插件需要监听文件上传事件或者提供一个工具当用户要求分析某个文件时插件去读取对应文件解析文本然后将文本内容返回给对话上下文。没有这个处理环节AI模型是无法知晓文件内容的。查看网络请求打开浏览器开发者工具的“网络”选项卡在上传文件和分析文件时观察前端发送给后端的请求Payload看看文件信息是否被正确传递。6.4 前端界面无法访问或白屏问题现象后端服务似乎启动了但访问http://localhost:8000出现白屏或前端资源加载错误。排查步骤检查端口占用确认端口8000或你配置的端口没有被其他程序占用。检查前端构建如果你修改了前端代码或环境变量可能需要重新构建前端静态资源。可以尝试运行npm run build如果项目根目录有package.json或在kirara启动命令中确认其是否自动处理了构建。检查反向代理配置如果已配置如果你使用了Nginx等反向代理确保其正确地将请求代理到了后端API通常是/api/路径和前端静态资源通常是/根路径或其他路径。一个常见的错误是代理配置没有正确处理WebSocket连接用于流式响应导致聊天功能异常。查看浏览器控制台错误白屏通常是前端JavaScript运行错误。打开浏览器开发者工具的“控制台”选项卡查看具体的错误信息这能提供最直接的线索。经过这几个月的深度使用kirara-ai给我的感觉更像是一个坚实的“地基”和一套高效的“工具箱”。它没有试图做一个大而全的、面向最终用户的AI产品而是精准地服务于开发者群体让开发者能基于它快速搭建出符合自己业务需求的、形态各异的AI应用。从简单的内部知识库问答机器人到复杂的、集成了多个外部系统的智能工作流助手它都能提供良好的支撑。它的插件系统是灵魂所在将AI的“思考”与现实的“行动”优雅地连接了起来。开发插件的过程其实就是教AI如何使用你现有业务系统的过程这种范式非常直观。当然它目前还在快速发展中一些高级功能如更精细的权限控制、多租户支持、更强大的运营后台等可能需要开发者自己动手补充。但考虑到其清晰的架构和活跃的社区这些都不是大问题。如果你正想尝试将AI能力集成到你的工作流或产品中但又不想陷入底层细节的泥潭lss233/kirara-ai是一个非常值得投入学习和使用的起点。从克隆项目到拥有一个能调用真实工具和你对话的AI助手可能只需要一杯咖啡的时间。这种快速获得正反馈的体验在技术探索中尤为珍贵。
Kirara-AI：全栈AI应用开发框架，快速构建生产级智能助手
发布时间：2026/5/16 7:59:26
1. 项目概述一个面向开发者的AI应用快速构建框架最近在折腾AI应用开发的朋友应该都体会过那种“从想法到原型”的中间环节有多磨人。你想做一个能联网搜索的智能客服或者一个能处理多格式文档的问答助手光是搭建基础环境、处理API调用、设计对话流、管理上下文就得花上好几天。更别提还要考虑前后端分离、状态管理、插件扩展这些工程化问题了。很多时候一个创意还没开始验证热情就先被繁琐的基建消耗殆尽了。lss233/kirara-ai这个项目就是为了解决这个痛点而生的。你可以把它理解为一个“AI应用的全栈脚手架”或者“AI领域的Next.js”。它的核心目标是让开发者尤其是全栈或后端开发者能够以极低的成本和极高的效率构建出功能完整、可扩展的生产级AI应用。它不是另一个聊天界面皮肤也不是简单的API封装而是一套包含了前端界面、后端服务、插件系统、工具调用、知识库集成等完整能力的开源框架。简单来说如果你厌倦了每次都要从零开始写OpenAI或Ollama的调用代码厌倦了手动拼接提示词和管理对话历史或者想快速集成Google Search、DALL-E画图、GitHub操作等能力到你的AI助手里面那么kirara-ai值得你花时间了解一下。它把那些重复的、通用的脏活累活都封装好了你只需要关注最核心的业务逻辑和创意实现。2. 核心架构与设计哲学拆解2.1 为什么是“全栈”框架市面上AI相关的开源项目很多但大致可以分为几类纯前端的聊天UI如chatbot-ui、纯后端的SDK或中间件如LangChain、LlamaIndex、以及一些偏向运营的对话平台。kirara-ai的定位非常明确它要提供一个开箱即用的、完整的应用解决方案。这意味着当你克隆下这个项目经过简单的配置和启动你得到的不只是一个后端API服务而是一个可以直接在浏览器里访问、拥有完整聊天界面、支持多会话、具备文件上传、插件调用等功能的Web应用。它的架构天然是前后端一体的后端用Python的FastAPI构建提供健壮的API和插件运行时前端则是一个现代化的React单页应用提供了优秀的用户体验。这种设计极大地降低了全链路开发的复杂度。背后的设计哲学是“约定大于配置”和“电池内置”。框架已经为你做出了许多合理的默认选择比如使用SQLite作为默认数据库来存储会话和消息使用FastAPI来构建高性能API使用ReactViteTailwind CSS构建响应式前端。你不需要在这些基础设施上做决策可以直接开始编写你的AI逻辑。同时它内置了诸如身份验证虽然默认是关闭的、会话管理、消息持久化、流式响应等“电池”让你不必重复造轮子。2.2 核心概念会话、消息与工具要理解kirara-ai必须先理清它的几个核心数据模型这关系到你如何组织你的应用逻辑。会话Session这是最顶层的概念代表一次独立的对话上下文。例如用户和你聊“周末去哪玩”是一个会话切换到另一个话题“帮我写段代码”就可以开启另一个新会话。每个会话是隔离的拥有独立的对话历史和上下文窗口。框架会负责会话的创建、列表查询、删除和切换。消息Message消息是会话中的基本单元。每条消息都有明确的角色user用户、assistantAI助手、system系统或tool工具。一个完整的对话就是一系列按时间顺序排列的消息。框架的核心工作之一就是维护这个消息列表并在调用AI模型时将合适的历史消息作为上下文Prompt发送过去。工具Tool这是kirara-ai最强大的特性之一也是实现AI“行动力”的关键。工具本质上是一个可以被AI模型调用的函数。当用户在对话中说“今天北京的天气怎么样”时AI模型如果支持函数调用会分析出用户的意图是查询天气然后决定调用一个名为get_current_weather的工具并生成符合工具参数要求的调用请求如location: “北京”。后端收到这个请求后会实际执行对应的Python函数获取真实的天气数据再将结果以tool角色的消息插入对话历史最后让AI模型生成一段友好的回复给用户。kirara-ai的插件系统就是建立在“工具”这个概念之上的。一个插件可以提供一个或多个工具。框架内置了一些常用工具插件比如网络搜索、维基百科查询、画图等更重要的是它提供了极其简便的方式来创建你自己的自定义工具。3. 快速上手与核心配置详解3.1 环境准备与一键启动kirara-ai对运行环境的要求非常友好。由于它是一个Python后端项目你只需要确保系统中有Python 3.10和pip即可。官方推荐使用uv这个更快的Python包管理器和安装器但用传统的pip也完全没问题。第一步是获取代码。推荐使用git进行克隆这样可以方便地更新。git clone https://github.com/lss233/kirara-ai.git cd kirara-ai接下来是安装依赖。项目根目录下的pyproject.toml文件定义了所有依赖。使用pip安装是最直接的方式pip install -e .这里的-e参数代表“可编辑模式”安装这意味着你修改项目中的Python代码后无需重新安装更改会立即生效非常适合开发。安装完成后最关键的一步就是配置。项目根目录下有一个.env.example文件这是一个环境变量配置模板。你需要将其复制一份并重命名为.envcp .env.example .env然后用文本编辑器打开这个新创建的.env文件。这里面的配置项决定了你的AI应用将如何运行。3.2 核心环境变量配置解析.env文件里的配置项看起来可能有点多但大部分都有合理的默认值初期你只需要关注几个核心的。1. AI模型后端配置 (KIRARA_LLM_MODEL)这是最重要的配置决定了你的应用使用哪个AI模型。kirara-ai支持多种后端OpenAI 兼容 API: 这是最常用的方式。你需要将KIRARA_LLM_MODEL设置为类似openai:gpt-4o或openai:gpt-3.5-turbo的格式。同时你必须在.env中设置OPENAI_API_KEY和OPENAI_BASE_URL。OPENAI_BASE_URL允许你指向任何兼容OpenAI API格式的服务比如官方OpenAI、Azure OpenAI或者是你在本地或云端部署的Ollama、vLLM、LM Studio等。KIRARA_LLM_MODELopenai:gpt-4o OPENAI_API_KEYsk-your-openai-key-here # 如果你用本地Ollama可以这样配置 # OPENAI_BASE_URLhttp://localhost:11434/v1Ollama 本地模型: 如果你在本地运行了Ollama想使用llama3、qwen等本地模型配置更简单。将KIRARA_LLM_MODEL直接设置为Ollama中的模型名即可框架会自动识别。KIRARA_LLM_MODELllama3.2:latest # 确保Ollama服务正在运行其他模型: 框架还实验性支持Anthropic Claude、Google Gemini等具体配置可参考项目文档。注意模型名称中的前缀如openai:是适配器标识告诉框架使用哪种协议去调用。务必确保格式正确这是新手最容易出错的地方之一。2. 前端与后端服务配置KIRARA_WEB_HOST和KIRARA_WEB_PORT: 这定义了后端API服务器监听的地址和端口默认是127.0.0.1:8000。如果你想让同一网络下的其他设备也能访问可以改为0.0.0.0。KIRARA_FRONTEND_URL: 这是前端页面访问后端的地址。在开发时如果你前后端分开启动比如用npm run dev跑前端可能需要将其设置为前端的开发服务器地址如http://localhost:5173。如果使用默认的一体化启动方式这个配置通常不需要修改。3. 数据与存储配置KIRARA_DATABASE_URL: 数据库连接字符串。默认使用SQLite数据文件会保存在项目目录下的data/kirara.db。如果你希望使用PostgreSQL或MySQL可以修改这个连接字符串。KIRARA_DATA_DIR: 所有应用数据包括数据库、上传的文件、插件数据等的根目录默认为./data。配置好.env文件后就可以启动应用了。回到项目根目录运行kirara start这个命令会同时启动后端API服务器和前端Web服务。稍等片刻在浏览器中打开http://localhost:8000或你配置的端口就能看到kirara-ai的聊天界面了。第一次打开可能会让你设置一个用户名这只是本地标识并非强认证。4. 插件系统深度解析与自定义开发4.1 内置插件与启用机制kirara-ai的强大很大程度上体现在其插件生态上。插件就是功能的模块化封装。项目内置了一些非常实用的插件你可以在.env文件中通过KIRARA_PLUGINS变量来启用它们。例如如果你想启用网络搜索和画图功能可以这样配置KIRARA_PLUGINSsearch, dalle多个插件用英文逗号分隔。重启应用后你就能在聊天界面中看到新启用的功能。以search插件为例当你在对话中问“最近有什么科技新闻”时AI模型会尝试调用搜索工具后端则会使用配置的搜索引擎如SERPAPI或Google Search API去获取真实结果然后整合进回复中。每个插件都可能需要自己的配置。例如search插件可能需要SERPAPI_KEYdalle画图插件需要OPENAI_API_KEY或DALL-E专用的API Key。这些配置同样需要写在.env文件里。启用插件后务必查阅项目的plugins目录下对应插件的README或源码了解其必要的环境变量。4.2 从零开始编写一个自定义插件虽然内置插件很实用但kirara-ai真正的魅力在于可以轻松创建属于自己的插件将任何API或本地能力赋予AI。下面我们以创建一个“工作日计算器”插件为例演示完整流程。第一步创建插件目录结构在项目的plugins目录下如果没有则创建新建一个文件夹例如my_workday_calculator。在里面创建两个必需的文件__init__.py和plugin.toml。plugins/ └── my_workday_calculator/ ├── __init__.py └── plugin.toml第二步定义插件元信息 (plugin.toml)这个文件告诉kirara-ai你的插件叫什么、有什么能力。[plugin] name “工作日计算器” description “计算两个日期之间的工作日天数排除周末和自定义节假日。” version “0.1.0” author “Your Name” # 定义插件提供的工具列表 [[tools]] name “calculate_workdays” description “计算两个日期之间的工作日天数。需要提供开始日期和结束日期日期格式为 YYYY-MM-DD。” parameters [ { name “start_date”, type “string”, description “开始日期格式 YYYY-MM-DD”, required true }, { name “end_date”, type “string”, description “结束日期格式 YYYY-MM-DD”, required true }, { name “holidays”, type “array”, description “自定义节假日列表格式为 [‘YYYY-MM-DD’, …]”, required false } ]这里定义了一个名为calculate_workdays的工具它需要start_date和end_date两个必填参数以及一个可选的holidays数组参数。description字段非常重要AI模型特别是大语言模型会阅读这个描述来决定是否以及如何调用这个工具所以请用清晰、准确的语言描述工具的功能和参数。第三步实现工具逻辑 (__init__.py)这个文件是插件的核心包含了工具函数的实际代码。from datetime import datetime, timedelta from dateutil import parser from kirara.plugin import Plugin import logging logger logging.getLogger(__name__) class MyWorkdayCalculatorPlugin(Plugin): async def calculate_workdays(self, start_date: str, end_date: str, holidays: list None): “”” 计算两个日期之间的工作日天数。 “”” try: start parser.parse(start_date).date() end parser.parse(end_date).date() if start end: start, end end, start # 确保开始日期不晚于结束日期 # 将字符串格式的节假日转换为日期对象 holiday_dates set() if holidays: for h in holidays: try: holiday_dates.add(parser.parse(h).date()) except Exception as e: logger.warning(f“无效的节假日格式被忽略: {h}, 错误: {e}”) # 遍历计算 current start workday_count 0 while current end: # 判断是否为周末 (周一为0周日为6) if current.weekday() 5 and current not in holiday_dates: workday_count 1 current timedelta(days1) return { “start_date”: start.isoformat(), “end_date”: end.isoformat(), “total_days”: (end - start).days 1, “workdays”: workday_count, “holidays_considered”: list(sorted([h.isoformat() for h in holiday_dates])) if holiday_dates else [] } except Exception as e: logger.error(f“计算工作日时出错: {e}”, exc_infoTrue) return {“error”: f“日期计算失败: {str(e)}”} # 这个类方法用于向框架注册工具 classmethod def tools(cls): return [cls.calculate_workdays]代码解析插件类需要继承自kirara.plugin.Plugin。工具函数如calculate_workdays是一个普通的async方法。kirara-ai内部使用异步框架所以建议工具函数也定义为异步的特别是当你的工具需要执行网络I/O操作时。函数的参数名必须与plugin.toml中定义的parameters完全对应。函数应该返回一个可序列化为JSON的字典这个结果会被框架捕获并作为tool角色的消息插入对话。最后必须实现classmethod tools(cls)返回一个包含所有工具函数的列表。这是框架发现工具的钩子。第四步启用你的插件在.env文件中将你的插件名称添加到KIRARA_PLUGINS列表中KIRARA_PLUGINSsearch, my_workday_calculator重启kirara服务。现在你就可以在聊天窗口中对AI说“请帮我计算从2024-12-01到2024-12-31的工作日天数排除12月25号。” AI会理解你的意图调用你编写的工具并返回精确的计算结果。实操心得编写自定义插件时工具函数的description和参数描述是“人机沟通”的桥梁务必写得清晰、无歧义。返回的数据结构尽量规范便于AI模型理解和组织成自然语言回复。对于可能出错的网络请求或复杂计算一定要做好异常捕获和日志记录这在调试时至关重要。5. 高级特性与生产化部署考量5.1 上下文管理与优化策略随着对话轮数增加上下文长度会不断增长。所有消息都发送给AI模型不仅会导致响应变慢还可能因超过模型的令牌限制而失败。kirara-ai提供了灵活的上下文管理策略。默认情况下框架会保留整个会话的历史消息。但你可以在.env中通过KIRARA_MAX_HISTORY_MESSAGES来限制保留的消息条数例如设置为20则只保留最新的20条消息。更高级的策略是使用“摘要”或“向量化记忆”。虽然这不是kirara-ai的内置功能但你可以通过自定义插件来实现。例如可以编写一个插件在对话历史达到一定长度时触发一个工具调用使用AI模型将之前的冗长对话总结成一段简短的摘要然后用这个摘要替换掉旧的历史消息从而在保留核心信息的前提下大幅压缩上下文。这需要你对对话状态有更强的把控。5.2 文件上传与多模态处理kirara-ai支持文件上传功能。用户可以在前端界面上传图片、PDF、Word、TXT等文件。文件上传后后端会将其存储在配置的KIRARA_DATA_DIR目录下。如何处理这些文件内容取决于你的AI模型能力和插件。例如如果使用支持视觉识别的模型如GPT-4V你可以将图片的路径或base64编码放入上下文让模型“看到”图片。对于PDF、Word等文档你需要一个插件来提取其中的文本。这可以通过集成PyPDF2、python-docx或Unstructured等库来实现。插件提取文本后可以将文本内容作为系统消息或用户消息的一部分送入对话上下文从而实现基于文档的问答。框架本身负责文件的存储和基础管理而文件内容的解析和利用则给了开发者极大的自定义空间。5.3 部署到生产环境将kirara-ai用于个人项目和小团队内部工具直接运行kirara start可能就够了。但如果要对外提供服务就需要考虑生产化部署。1. 数据库升级默认的SQLite在并发写入时可能成为瓶颈。建议更换为PostgreSQL或MySQL。只需修改.env中的KIRARA_DATABASE_URL例如KIRARA_DATABASE_URL“postgresql://user:passwordlocalhost:5432/kirara_db”并确保已安装相应的数据库驱动如psycopg2。2. 反向代理与HTTPS使用Nginx或Caddy作为反向代理将kirara-ai的后端API默认端口8000和前端静态文件代理出去。同时配置SSL证书启用HTTPS这是生产环境的必备安全措施。3. 进程管理使用systemd、Supervisor或Docker来管理kirara进程确保其崩溃后能自动重启。kirara start命令启动的其实是Uvicorn服务器用于后端和前端静态服务。在生产环境你可能希望将它们分开管理或者使用Gunicorn配合Uvicorn工人进程来获得更好的并发性能。4. 身份验证与授权kirara-ai默认没有开启强制的用户认证这对于公开服务是危险的。你需要自行实现或集成认证层。一种方案是在Nginx层面配置HTTP Basic Auth或集成OAuth代理如oauth2-proxy。另一种更深入的方式是修改kirara-ai的后端代码在FastAPI应用中添加依赖项对需要保护的API路由进行JWT令牌验证。5. 容器化部署使用Docker和Docker Compose是最简洁的部署方式之一。你可以编写一个Dockerfile来构建包含所有依赖的镜像再用docker-compose.yml来定义服务应用、数据库等。这能保证环境的一致性极大简化部署流程。社区可能有现成的Docker配置可供参考。6. 常见问题与故障排查实录在实际使用和部署kirara-ai的过程中你可能会遇到一些典型问题。这里记录了几个我踩过的坑和解决方案。6.1 插件加载失败问题现象在.env中配置了插件但启动时日志报错Plugin ‘xxx’ not found或者前端看不到插件功能。排查步骤检查插件名称确保KIRARA_PLUGINS中的插件名称与插件目录名完全一致且目录位于项目的plugins/路径下。名称大小写敏感。检查插件结构确认插件目录下必须有__init__.py和plugin.toml两个文件且plugin.toml格式正确可以使用TOML在线校验工具。检查Python导入在__init__.py中确保插件类继承自kirara.plugin.Plugin并且类名与plugin.toml中的[plugin]部分没有直接关联但tools()类方法必须正确实现。可以尝试在项目根目录下打开Python交互环境手动from plugins.xxx import *看是否能成功导入。查看启动日志kirara start的启动日志会详细列出加载了哪些插件。如果插件有语法错误也会在这里显示。仔细阅读错误信息。6.2 AI模型无法调用或响应慢问题现象聊天界面显示发送失败或者等待响应时间极长。排查步骤确认模型配置首先检查.env中的KIRARA_LLM_MODEL和对应的API Key、Base URL是否正确。对于Ollama确认模型名正确且已通过ollama pull下载。测试API连通性如果是使用OpenAI兼容API可以用curl命令直接测试curl http://localhost:11434/v1/chat/completions \ -H “Content-Type: application/json” \ -H “Authorization: Bearer ollama” \ -d ‘{ “model”: “llama3.2”, “messages”: [{“role”: “user”, “content”: “Hello”}], “stream”: false }’将URL和model替换为你的配置。这能帮你确定问题是出在kirara-ai还是底层API服务。检查网络与代理如果你的环境需要通过代理访问外部API需要确保kirara-ai的进程能正确使用代理。可以在启动命令前设置环境变量如export HTTP_PROXYhttp://your-proxy:port。模型本身响应慢一些本地大模型或网络状况不佳时响应本身就很慢。可以尝试在前端发送一个简单问题观察后端日志中从发送请求到收到响应的耗时。6.3 文件上传后无法被AI处理问题现象文件可以成功上传但在对话中提及文件内容时AI似乎“看不到”文件。排查步骤确认文件存储路径检查.env中的KIRARA_DATA_DIR确认上传的文件确实存储在了该目录下的uploads子文件夹中。检查插件或上下文处理框架只负责存储文件不负责自动解析内容。你需要对于图片确认你使用的AI模型支持视觉识别如GPT-4V并且你的请求中正确包含了图片的引用例如通过插件将图片转换为base64编码并放入消息内容。对于文档你需要编写或启用一个文档处理插件。该插件需要监听文件上传事件或者提供一个工具当用户要求分析某个文件时插件去读取对应文件解析文本然后将文本内容返回给对话上下文。没有这个处理环节AI模型是无法知晓文件内容的。查看网络请求打开浏览器开发者工具的“网络”选项卡在上传文件和分析文件时观察前端发送给后端的请求Payload看看文件信息是否被正确传递。6.4 前端界面无法访问或白屏问题现象后端服务似乎启动了但访问http://localhost:8000出现白屏或前端资源加载错误。排查步骤检查端口占用确认端口8000或你配置的端口没有被其他程序占用。检查前端构建如果你修改了前端代码或环境变量可能需要重新构建前端静态资源。可以尝试运行npm run build如果项目根目录有package.json或在kirara启动命令中确认其是否自动处理了构建。检查反向代理配置如果已配置如果你使用了Nginx等反向代理确保其正确地将请求代理到了后端API通常是/api/路径和前端静态资源通常是/根路径或其他路径。一个常见的错误是代理配置没有正确处理WebSocket连接用于流式响应导致聊天功能异常。查看浏览器控制台错误白屏通常是前端JavaScript运行错误。打开浏览器开发者工具的“控制台”选项卡查看具体的错误信息这能提供最直接的线索。经过这几个月的深度使用kirara-ai给我的感觉更像是一个坚实的“地基”和一套高效的“工具箱”。它没有试图做一个大而全的、面向最终用户的AI产品而是精准地服务于开发者群体让开发者能基于它快速搭建出符合自己业务需求的、形态各异的AI应用。从简单的内部知识库问答机器人到复杂的、集成了多个外部系统的智能工作流助手它都能提供良好的支撑。它的插件系统是灵魂所在将AI的“思考”与现实的“行动”优雅地连接了起来。开发插件的过程其实就是教AI如何使用你现有业务系统的过程这种范式非常直观。当然它目前还在快速发展中一些高级功能如更精细的权限控制、多租户支持、更强大的运营后台等可能需要开发者自己动手补充。但考虑到其清晰的架构和活跃的社区这些都不是大问题。如果你正想尝试将AI能力集成到你的工作流或产品中但又不想陷入底层细节的泥潭lss233/kirara-ai是一个非常值得投入学习和使用的起点。从克隆项目到拥有一个能调用真实工具和你对话的AI助手可能只需要一杯咖啡的时间。这种快速获得正反馈的体验在技术探索中尤为珍贵。
