1. 项目概述一个为边缘而生的小型AI大脑如果你和我一样对“把AI助手搬回家”这件事有执念同时又对动辄几十GB的模型和复杂的云服务架构感到头疼那么OpenGrug这个项目可能就是你在寻找的那个“刚刚好”的答案。它不是什么试图颠覆行业、对标GPT-4的庞然大物而是一个专为2B到10B参数级别的小型语言模型LLM设计的、轻量级、可自托管的AI助手框架。简单来说它让你能在自己的树莓派、老旧笔记本或者便宜的VPS上跑起一个真正能干活的、有记忆、会思考、能调用工具的智能体Agent并且通过Slack与你自然交互。这个项目的核心哲学非常“极客”也极其务实为什么要把数据和个人助理交给云端那个“大脑袋”当本地这个“小脑袋”也能干得很好而且完全属于你OpenGrug的设计目标就是“最小化基础设施依赖最大化本地智能”。它把整个系统——从模型推理、工具调用、记忆存储到任务调度——都塞进了一个Docker容器里。这意味着你只需要一个能跑Docker的环境就能拥有一个7x24小时在线、能处理你的待办事项、记录笔记、回答基于你个人知识库的问题甚至能按计划执行任务的私人助理。它特别适合几类人家庭实验室Homelab爱好者喜欢完全掌控自己的数字生活预算有限的开发者或小团队希望以极低成本引入自动化助理能力以及对数据隐私和离线工作有强烈需求的用户。OpenGrug不追求最前沿的模型能力而是追求在有限资源下的最高可靠性和实用性这种“够用就好”的工程思维正是它在众多AI Agent项目中显得独特的原因。2. 核心架构与设计哲学拆解OpenGrug的架构清晰得像一张电路图没有一丝冗余。它没有采用微服务那套复杂的拆分而是将所有核心模块紧密集成在一个应用中通过清晰的目录结构和职责分离来保证可维护性。这种“单体但模块化”的设计是应对边缘部署资源限制的聪明选择。2.1 三层核心架构交互、思考与记忆整个系统可以抽象为三层理解这三层是理解OpenGrug如何工作的关键。第一层交互层app.pycore/queue.py这是系统的门面负责与外部世界目前主要是Slack通信。所有来自Slack的消息首先进入一个消息队列。这个队列设计非常关键它确保了即使有多个用户同时向助理提问或者模型正在处理一个长任务时请求也不会丢失或冲突。队列会以“单线程排水”的方式一个一个地处理消息完美避免了在并发场景下可能出现的状态混乱或资源争抢问题。这就像银行只有一个办事窗口但大家都会取号排队保证了业务处理的原子性和顺序性。第二层思考与调度层core/router.pycore/llm.pycore/registry.py这是Grug的“大脑”。router.py是总调度中心它接收来自队列的用户消息然后执行一个经典的“思考-行动”循环思考将用户消息、当前会话上下文、可用的工具列表以及所有历史指令instructions组合成一个完整的系统提示prompt发送给本地的Ollama模型。解析模型会以特定的JSON格式回复声明它想调用哪个工具以及传入什么参数。OpenGrug直接使用Ollama原生的工具调用接口/api/chat这比让模型输出文本再通过正则表达式去解析要稳定和高效得多。调度与安全门控registry.py工具注册表会验证模型返回的调用请求工具是否存在参数是否符合预定义的JSON Schema更重要的是它会根据工具是否被标记为“破坏性”如删除文件、修改系统配置来决定是否需要人工介入Human-in-the-Loop, HITL。安全工具直接执行危险工具则会向用户弹出一个确认按钮。这个设计在赋予AI自主性的同时牢牢守住了安全的底线。第三层记忆与持久层core/storage.pycore/vectors.pybrain/目录这是Grug的“长期记忆”和“知识库”。其设计哲学堪称一绝Markdown文件是唯一的真相来源Source of Truth而SQLite数据库只是用于加速查询的缓存或索引。storage.py负责将所有对话、笔记、任务等内容以纯文本Markdown格式按日期组织存放在brain/daily_logs/目录下。这种设计的好处是极致透明和可移植性。你可以用任何文本编辑器查看、修改历史整个“大脑”的迁移就是复制一个文件夹那么简单。vectors.py基于这些Markdown文件的内容使用sentence-transformers生成文本的向量嵌入embeddings然后存入sqlite-vec扩展的SQLite数据库中。这构成了一个本地的语义搜索系统RAG让Grug能快速从你的历史笔记和对话中找到相关信息来回答问题。sessions.py管理着活跃的Slack会话每个线程对应SQLite中的一条记录保存着最近的对话上下文以保证聊天的连贯性。注意这种“Markdown为真SQLite为缓存”的设计意味着即使向量数据库损坏你也能从Markdown文件中完整重建索引。数据安全性和可恢复性被放在了首位。2.2 自学习与进化机制OpenGrug超越简单问答机器人的地方在于它的“学习”能力。这主要通过两个模块实现core/context.py它在组装每次请求的系统提示时会注入所有通过add_instruction工具添加的“指令”。这些指令可以是规则“永远用中文回复”、偏好“总结时要分点列出”或事实“我的项目代码存放在~/projects”。它们成为了模型思考的固定背景知识。tools/instructions.py中的事后回顾After Action Report, AAR工具这是一个强大的元认知工具。你可以让Grug回顾过去的某段对话分析其中的决策、错误或成功模式并将学到的“经验教训”自动生成一条新的instruction添加到知识库中。这样Grug就能从历史交互中不断进化越来越贴合你的使用习惯。2.3 后台守护者workers/background.py这个模块是让Grug从“响应式机器人”变为“主动式助理”的关键。它包含了几个后台守护进程启动总结每次Grug重启时会快速总结上次关闭后的日志帮助模型快速进入状态。空闲会话压缩定期检查Slack会话将长时间不活动的对话用LLM总结后存入Markdown日志然后清理SQLite中的原始记录防止数据库无限膨胀。夜间例行任务每天执行一次全局日志总结等维护任务。调度器轮询以固定间隔如每分钟检查scheduler中是否有到期的定时任务如提醒、自动报告并触发执行。正是这些后台进程让Grug具备了“计划”和“自治”的能力。3. 从零开始部署与深度配置指南理论讲完我们动手把它跑起来。OpenGrug的部署力求简化但理解每一步背后的配置能让你更好地驾驭它。3.1 硬件与基础环境准备首先明确你的部署目标。OpenGrug非常灵活但不同的硬件配置决定了你能跑什么样的模型。部署场景推荐硬件配置可选模型举例 (Ollama)特点与预期入门体验树莓派4B 8GB, 或任何4GB内存的x86设备tinyllama(1.1B),phi(2.7B)能跑起来完成简单问答和笔记。工具调用和复杂推理较慢。平衡实用台式机/笔记本16GB RAM4核CPUgemma2:2b,mistral:7b,qwen2.5:3b推荐起点。7B模型在工具调用、逻辑推理上已有不错表现响应速度可接受。流畅生产专用服务器/VPS32GB RAMGPU更佳llama3.2:3b,gemma2:7b,qwen2.5:7b响应迅速能流畅处理多步复杂任务RAG检索质量高。确定硬件后确保系统已安装Docker和Docker Compose这是OpenGrug的官方运行方式。Ollama用于托管本地LLM。请根据官方文档安装并至少拉取pull一个上述推荐的小模型例如ollama pull gemma2:2b。一个Slack工作区你需要创建一个Slack App来获得API令牌。3.2 详细配置步骤与避坑要点官方提供的./setup.sh脚本是一个交互式向导但对于想深入了解或进行自定义部署的用户我们拆解其每一步。第一步克隆与初步配置git clone https://github.com/cjoen/opengrug.git cd opengrug # 初始化核心的“大脑”目录所有持久化数据将在这里 mkdir -p brain第二步创建Slack App并获取令牌这是最容易出错的一步。访问 api.slack.com/apps 创建新应用。SLACK_BOT_TOKEN(Bot User OAuth Token)在功能页面启用“Socket Mode”这是OpenGrug通信的基础。在“OAuth Permissions”页面给Bot添加以下权限作用域scopesapp_mentions:readchannels:history(如果你要在频道中使用)chat:writegroups:history(如果你要在私密频道中使用)im:historyim:writereactions:write(用于HITL确认按钮)安装应用到你的工作区即可获得以xoxb-开头的Bot Token。SLACK_APP_TOKEN(App-Level Token)在“基本信息”页面找到“App-Level Tokens”创建一个新的Token作用域只选择connections:write。你会获得一个以xapp-开头的App Token。第三步深度编辑配置文件grug_config.jsonsetup.sh会生成一个基础配置但以下部分值得你仔细推敲{ llm: { model: gemma2:2b, // 与你本地Ollama拉取的模型名一致 ollama_host: http://host.docker.internal:11434, // Docker容器内访问宿主机Ollama的地址 context_window: 4096, // 模型上下文长度不要超过模型实际能力 temperature: 0.1, // 低温度使输出更确定适合工具调用 confidence_threshold: 0.7 // 模型返回的“置信度”低于此值会要求澄清 }, memory: { max_summary_tokens: 500, tail_lines: 20, // 每次提问携带的最近对话行数影响上下文长度 thread_idle_timeout_hours: 168, // 7天超过此时长的闲置会话将被压缩 rag: { enabled: true, top_k: 3 // 语义搜索返回的最相关片段数量 } }, storage: { base_dir: /app/brain, // Docker容器内的路径对应宿主的 ./brain session_ttl_days: 30 }, queue: { worker_count: 1 // 通常设为1与单Ollama实例匹配。如果你部署了多个Ollama可增加 } }关键配置解析ollama_host在Docker Compose网络内host.docker.internal指向宿主机。确保宿主机Ollama服务默认11434端口可访问且防火墙规则允许。temperature对于工具调用这类需要精确性的任务建议设置在0.1-0.3之间以减少模型的随机性。worker_count除非你配置了多个Ollama实例做负载均衡否则保持为1。增加此值不会提升单个请求速度只会导致更多请求堆积在Ollama处。第四步通过环境变量覆盖配置更灵活的方式是通过Docker环境变量覆盖配置这在云部署时尤其有用。在docker-compose.yml同目录创建.env文件OLLAMA_HOSThttp://192.168.1.100:11434 # 如果Ollama不在宿主机填写实际IP SLACK_BOT_TOKENxoxb-your-bot-token SLACK_APP_TOKENxapp-your-app-token DOCKER1 # 告诉应用它在容器内运行第五步启动与验证# 使用官方脚本 ./setup.sh # 或手动启动 docker-compose up -d启动后查看日志确认无报错docker-compose logs -f app你应该看到连接Slack成功、加载工具、初始化向量数据库等日志。在Slack中邀请你创建的Bot进入频道或直接私信它发送“hello”测试。实操心得第一次启动时向量数据库初始化为现有Markdown文件生成嵌入可能需要几分钟具体取决于brain/目录下历史数据的多少。期间Grug可能响应缓慢这是正常现象。耐心等待日志中出现“Vector store initialized”后再进行复杂操作。4. 核心工具使用详解与自动化场景构建Grug的真正威力在于其工具集。理解并熟练运用这些工具才能将它从聊天机器人升级为生产力伙伴。4.1 基础工具打造外部记忆系统/note或add_note这是最常用的工具。你可以随时告诉Grug“记录一下今天和客户A开会决定下周交付原型。” 这条记录会以Markdown格式存入当天的日志文件并立即被编入向量索引。之后你可以问“上周和客户A开会说了什么” Grug就能通过语义搜索找到相关记录。技巧笔记内容尽量具体、包含关键实体人名、项目名、日期。例如“修复了登录API的500错误”比“修了个bug”更容易被检索到。/task或add_task管理个人或团队任务板。你可以说“添加一个任务『编写项目周报』优先级高截止日期本周五。” Grug会将其加入任务列表。list_tasks可以查看所有任务summarize_board可以获得一个LLM生成的待办事项概述。技巧利用自然语言描述截止日期和优先级Grug的模型能很好地解析“明天”、“下周一”、“高优先级”这样的表述。4.2 进阶工具实现个性化与自动化add_instruction这是塑造Grug个性的关键。例如add_instruction content当用户询问天气时总是建议他查看权威天气预报网站并说明我无法获取实时数据。add_instruction content所有总结性回复请使用分点列表-的形式输出。add_instruction content我的名字是Alex在提到我时请使用这个名字。添加后这些指令会成为系统提示的一部分永久影响Grug的行为模式。run_aar(After Action Report)学习进化引擎。选择一个过去的对话线程让Grug分析。例如在一次Grug错误理解了你的复杂指令后你可以说“对刚才关于数据导出的对话运行AAR。” Grug会分析哪里出了错并可能生成一条如“当用户提到『导出所有数据』时需要先确认时间范围和格式”的新指令并询问你是否添加。同意后它就学会了。调度器工具 (add_scheduled_task)实现定时自动化。这可能是最强大的功能之一。场景一每日提醒add_scheduled_task cron0 9 * * 1-5 commandremind 用户 standup meeting in 15 minutes—— 每周一到五早上9点提醒站会。场景二自动报告add_scheduled_task cron0 18 * * 5 commandsummarize_board—— 每周五晚6点自动总结任务板并发送到频道。场景三周期性笔记add_scheduled_task cron0 20 * * * commandadd_note content每日晚间日志检查服务器状态完成。—— 每晚8点自动添加一条运维日志。参数详解cron: 标准的cron表达式非常灵活。command: 可以是任何Grug能理解的指令包括调用其他工具。description: 可选帮助记忆这个定时任务的目的。4.3 构建自动化工作流示例假设你想让Grug帮你管理一个简单的家庭实验室知识库初始化使用add_note工具将你的服务器IP、服务端口、常用命令如重启服务的docker命令记录下来。添加操作规则add_instruction content当用户询问服务器状态时首先检索笔记中关于该服务器的信息然后建议通过SSH执行特定检查命令但提醒用户最终需要手动操作。设置健康检查add_scheduled_task cron0 */2 * * * commandadd_note content定时检查所有核心服务运行正常。这是一个模拟检查实际需对接监控API—— 每两小时添加一条模拟检查日志。每周清理提醒add_scheduled_task cron0 9 * * 7 commandremind 用户 记得清理Docker无用镜像和容器日志—— 每周六早上提醒。这样Grug就成了一个集知识库、操作手册和定时提醒于一身的家庭实验室助手。5. 运维、调试与性能优化实战将Grug稳定地运行起来只是第一步长期稳定运行并优化其性能需要了解更多细节。5.1 监控与日志分析OpenGrug的日志输出到Docker容器的标准输出通过docker-compose logs查看。你需要关注几种关键日志连接与心跳启动时应有“Connected to Slack”和定期的心跳日志表明Slack连接健康。工具调用每次模型决定调用工具时会有类似Dispatching to tool: add_note的日志并显示参数。这是调试工具调用逻辑的主要依据。队列状态当有并发请求时可以看到Queue depth: X的日志帮助你了解处理压力。后台任务空闲压缩、夜间总结等任务的开始和完成日志。一个高效的技巧是将日志导入到journald或loki等日志集中管理系统并设置告警规则例如“连续1分钟未收到心跳日志”则触发告警。5.2 常见问题排查速查表以下是我在长期使用中遇到的一些典型问题及解决方法问题现象可能原因排查步骤与解决方案Slack消息无回复1. Slack令牌无效或权限不足。2. Docker网络问题容器无法访问宿主机Ollama。3. 模型加载失败或崩溃。1. 检查docker-compose logs是否有Slack连接错误。重新核对Bot Token和App Token确保Socket Mode已启用。2. 在容器内执行curl http://host.docker.internal:11434/api/tags测试是否能访问Ollama API。3. 检查宿主机Ollama服务状态ollama list并查看Ollama日志。工具调用失败提示“Tool X not found”1. 工具未在registry.py中正确注册。2. 模型返回的工具名与注册名不匹配大小写、下划线等。1. 检查tools/目录下的工具文件是否被正确导入到app.py的注册部分。2. 查看模型返回的原始JSON日志确认tool字段的值是否完全匹配注册名。可在instruction中明确告诉模型工具的确切名称。RAG搜索返回无关内容1. 向量索引未更新或损坏。2. 嵌入模型sentence-transformer不适用于你的文本领域。3.top_k参数设置过大或过小。1. 重启应用会触发向量库重建。也可手动删除brain/下的*.sqlite文件后重启。2. 考虑在vectors.py中更换更适合你语料的嵌入模型如all-MiniLM-L6-v2是通用型paraphrase-*系列适合语义匹配。3. 调整grug_config.json中rag.top_k的值通常3-5是一个好的起点。响应速度极慢1. 本地模型推理速度慢。2. 上下文过长导致每次提示词都非常庞大。3. 消息队列堵塞。1. 考虑更换更小的模型如从7B换到3B或为服务器增加GPU资源。2. 调整memory.tail_lines减少携带的历史消息行数。定期使用summarize工具压缩长对话。3. 检查docker-compose logs看队列深度。如果持续很高考虑是否是某个请求卡住如等待HITL确认或模型响应超时。定时任务不执行1. 调度器后台进程未运行或崩溃。2. Cron表达式错误。3. 系统时间不同步在容器内。1. 查看日志中是否有scheduler相关的错误。重启background工作进程。2. 使用在线Cron表达式验证器检查语法。注意容器内是UTC时间。3. 在docker-compose.yml中为容器挂载宿主机的/etc/localtime文件并设置TZ环境变量。5.3 性能优化与高级调优当Grug成为日常依赖后你可能希望它更快、更聪明。1. 模型层面优化量化使用Ollama的量化版本模型如qwen2.5:3b-instruct-q4_K_M。在几乎不损失精度的情况下大幅降低内存占用和提升推理速度。提示词工程在core/context.py中优化系统提示词。更清晰、更结构化的提示词能引导小模型更好地遵循指令、选择工具。例如明确工具调用的格式范例。调整生成参数在grug_config.json的llm部分降低temperature(如0.1) 和top_p(如0.9) 可以使输出更稳定、更可预测这对于工具调用至关重要。2. 系统层面优化为Ollama启用GPU如果你的宿主机有NVIDIA GPU确保安装了nvidia-container-toolkit并在运行Ollama时使用OLLAMA_FLASH_ATTENTION1等环境变量或在Ollama的Modelfile中指定GPU层数。这能带来数倍的速度提升。调整Docker资源限制在docker-compose.yml中为opengrug服务设置合理的cpus和mem_limit避免与宿主机上其他服务尤其是Ollama争抢资源。优化向量搜索如果brain/目录下的Markdown文件非常多超过1000个RAG检索可能会变慢。可以考虑定期归档旧日志只对近期高频访问的数据建立索引。调整sqlite-vec的索引参数如使用HNSW索引但这需要修改vectors.py的代码。3. 扩展性考虑多Ollama实例负载均衡这是应对高并发的终极方案。你可以部署多个Ollama实例甚至在不同机器上然后在OpenGrug的queue配置中增加worker_count并修改llm.py中的OllamaClient使其成为一个简单的负载均衡客户端轮流或随机向多个Ollama后端发送请求。这能显著提高系统的整体吞吐量。自定义工具开发OpenGrug的工具系统是开放的。参考tools/目录下的现有工具你可以很容易地添加新的工具。例如添加一个control_light工具通过调用Home Assistant的API来控制智能家居或者添加一个deploy_service工具通过SSH在远程服务器上执行部署脚本。这能将Grug的能力无限延伸到你的任何自动化场景中。6. 安全、备份与灾难恢复策略将AI助手部署在本地安全性和数据可靠性完全由你负责。安全最佳实践网络隔离将运行OpenGrug和Ollama的服务器放在家庭网络内网不要将相关端口如11434暴露在公网。Slack通信使用WebSocket over Socket Mode是出向连接相对安全。令牌管理绝对不要将SLACK_BOT_TOKEN和SLACK_APP_TOKEN提交到任何版本控制系统如Git。始终使用.env文件管理并确保该文件在.gitignore中。最小权限原则在Slack中只授予Bot完成其功能所必需的最少权限。定期审查权限列表。HITL人工介入审阅定期检查grug_config.json中哪些工具被标记为“破坏性”destructive: true。确保这些工具如未来可能添加的文件删除、系统命令执行等的HITL开关始终开启。备份策略你的所有数据都在./brain目录下。这是一个纯文本和SQLite文件的集合备份极其简单。定期备份使用rsync或borg等工具将整个brain目录备份到另一块硬盘或云存储确保加密。版本控制你甚至可以将brain/daily_logs/目录初始化成一个Git仓库定期提交Markdown文件的变更。这不仅能备份还能看到笔记的历史演变。关键文件brain/instructions.md文件包含了所有你精心调教的指令建议单独备份。灾难恢复如果服务器完全崩溃恢复步骤如下在新机器上安装Docker, Docker Compose和Ollama。拉取相同的OpenGrug代码版本。将备份的brain目录覆盖到项目根目录。配置好.env文件中的Slack令牌。执行docker-compose up -d。 由于向量数据库SQLite可以从Markdown文件重建所以即使只备份了Markdown文件恢复后Grug在重启时也会自动重建索引知识不会丢失。这种设计使得恢复过程非常鲁棒。经过以上从架构到实操从部署到优化的完整梳理你应该已经能够驾驭OpenGrug这个强大的本地AI助手了。它的魅力不在于用了多炫酷的技术而在于用一种简洁、可控、可依赖的方式将大模型的能力真正落地到个人或小团队的日常场景中。从今天开始试着让它帮你记流水账、管理每周TODO、或者只是作为一个随时可问的本地知识库。你会发现这个“小脑袋”带来的效率提升和心智负担的减轻是实实在在的。