本文介绍了Krull AI——一个专为完全离线运行设计的自托管AI技术栈。该系统整合了聊天界面、LLM推理、网络搜索聚合、离线知识库、地图服务和地理编码等多项功能，通过Docker Compose实现一键部署。特别值得一提的是其与Claude Code的深度集成能力，为开发者提供了无需依赖云服务的完整AI工作环境。

Krull AI：完整的本地自托管AI技术栈\n\n## 自主可控的AI基础设施\n\n在云服务主导AI应用开发的今天，一个完全自托管、无需API密钥、甚至无需互联网连接的AI技术栈显得尤为珍贵。Krull AI正是这样一个项目——它的名字源于"Knowledge, Reasoning, and Unified Local Learning"，体现了构建本地化AI能力的核心理念。\n\n无论是出于数据隐私考虑、网络环境限制，还是对技术自主可控的追求，Krull AI都提供了一个令人信服的解决方案。它不仅仅是一个聊天机器人，而是一套完整的基础设施，涵盖了从模型推理到知识检索、从网络搜索到地图服务的全方位能力。\n\n## 架构概览：七大核心服务\n\nKrull AI采用微服务架构，通过Docker Compose编排七个核心组件：\n\n### 1. Open WebUI（端口3000）\n\n基于浏览器的聊天界面，支持RAG（检索增强生成）、工具调用和管道处理。这是用户与系统交互的主要入口，提供了类似ChatGPT的对话体验，但完全运行在本地。\n\n### 2. Ollama（内部服务）\n\nGPU加速的LLM推理引擎，负责模型的加载和推理。它支持多种开源模型，并能够充分利用NVIDIA GPU的计算能力。\n\n### 3. LiteLLM（端口4000）\n\nAPI网关服务，使Claude Code等外部工具能够与本地模型通信。这是Krull AI与现有开发工作流集成的关键桥梁——开发者可以继续使用熟悉的Claude Code界面，但背后的"大脑"换成了本地运行的开源模型。\n\n### 4. SearXNG（内部服务）\n\n元搜索引擎，聚合多个搜索引擎（Google、DuckDuckGo、Brave等）的结果。当系统需要获取实时信息时，SearXNG提供了去中心化的搜索能力，避免依赖单一搜索引擎。\n\n### 5. Martin（端口8070）\n\n离线地图瓦片服务器，支持PMTiles和MBTiles格式。这一组件使得系统能够在无网络环境下提供地图浏览、地理编码和路径规划能力，对于野外作业、应急响应等场景尤为实用。\n\n### 6. Photon（内部服务）\n\n离线地理编码和地点搜索服务。与Martin配合，实现了完整的地图功能栈，无需调用Google Maps等商业API。\n\n### 7. Kiwix（端口8090）\n\n离线维基百科和知识档案服务器。通过下载ZIM格式的离线数据库，系统可以在断网环境下访问海量知识内容，从百科全书到技术文档，从经典文学到学术论文。\n\n## 核心设计理念：与Claude Code的深度集成\n\nKrull AI的一个独特设计目标是与Claude Code的无缝集成。开发者无需改变使用习惯——原有的技能、钩子、CLAUDE.md文件和工作流都能继续工作，只是背后的模型从云端API切换到了本地推理。\n\n这种设计体现了对开发者工作流的深度尊重。Claude Code已成为许多开发者的日常工具，而Krull AI提供了一种"换芯不换壳"的私有化方案。通过LiteLLM的API网关，本地模型以兼容OpenAI API的格式暴露服务，Claude Code可以像连接OpenAI或Anthropic API一样连接本地模型。\n\n## 离线能力的全面覆盖\n\nKrull AI的真正实力在断网环境下才能充分展现。项目提供了丰富的离线数据下载工具：\n\n### 离线地图数据\n\n支持下载多种类型的地图数据：\n\n- 基础地图：OpenStreetMap矢量瓦片，包含道路、建筑、水域、土地利用等信息\n- 地形数据：全球高程数据，支持山体阴影、等高线和3D地形渲染\n- 海图：NOAA nautical charts，包含水深测量、浮标、航道、海底底质等专业航海信息\n- 航空图：FAA VFR Sectional Charts，包含机场、空域分类、导航辅助设施、障碍物等航空信息\n\n覆盖范围从美国各州到全球，数据量从几十MB到80GB不等，用户可根据需求灵活选择。\n\n### 离线知识库\n\n通过Kiwix支持多种知识资源的离线访问：\n\n- 维基百科：从精简版（无图片，约25GB）到完整版（含图片，约115GB），甚至可按主题下载（如医学专题约2GB）\n- 开发者文档：Python、JavaScript、TypeScript、Node.js、Git、Docker、Bash等开发必备文档\n- Stack Exchange：Stack Overflow、Server Fault、Super User等技术问答社区内容\n- 古腾堡计划：6万多本免费电子书，按小说、科学、STEM等分类组织\n\n### 离线搜索能力\n\n即使在没有互联网的情况下，SearXNG仍可搜索已下载的本地知识库，实现离线环境下的信息检索。\n\n## 模型管理与优化\n\nKrull AI对模型管理进行了精心设计，特别是针对与Claude Code的兼容性：\n\n### 推荐的Qwen3.5模型\n\n项目推荐使用frob/qwen3.5-instruct系列模型，原因如下：\n\n- 工具调用兼容性：该模型变体能够生成符合Anthropic风格的tool_use代码块，这是Claude Code正确解析工具调用所必需的。相比之下，qwen2.5-coder模型将工具调用输出为纯JSON文本，会导致工具调用失败。\n\n- 思考模式优化：frob/qwen3.5-instruct是Qwen3.5的变体，禁用了思考模式，响应速度更快，同时保持了相同的模型权重和输出质量。\n\n### 参数调优\n\n项目为不同场景提供了预设的参数配置：\n\n- 通用场景：temperature 0.7，top_p 0.8，平衡创造性和一致性\n- 编程场景：可通过环境变量覆盖为temperature 0.6，降低随机性，提高代码准确性\n\n### 模型选择指南\n\n根据GPU显存容量，用户可选择不同规模的模型：\n\n| 模型 | 显存需求 | 适用场景 |\n|------|----------|----------|\n| qwen3.5-instruct:4b | ~3GB | 快速响应，轻量硬件 |\n| qwen3.5-instruct:9b | ~6GB | 推荐配置，编程+工具调用 |\n| qwen3.5-instruct:27b | ~16GB | 最佳质量，需要高端GPU |\n\n## 智能过滤器与增强功能\n\nKrull AI不仅仅是各组件的简单堆砌，还通过智能过滤器增强了本地模型的能力：\n\n- 上下文管理：优化长对话的上下文窗口使用，避免早期信息丢失\n- 自动网络搜索：在需要时自动触发SearXNG搜索，补充模型知识\n- 离线知识注入：将Kiwix中的相关知识自动注入提示词，增强回答准确性\n- 计划模式保护：在复杂任务规划时提供引导，防止模型偏离目标\n\n这些过滤器通过./krull setup命令一键安装，显著提升了本地模型的实用性和可靠性。\n\n## 部署与使用\n\nKrull AI的部署流程设计得尽可能简单：\n\nbash\ngit clone git@github.com:odysseyalive/krull-ai.git\ncd krull-ai\n./krull start\n\n\n首次运行会拉取Docker镜像（约10GB）并下载维基百科入门数据（约5MB），耗时几分钟。之后，系统提供了一系列管理命令：\n\n- ./krull pull-model：下载和管理模型\n- ./krull download-maps：下载离线地图数据\n- ./krull download-wikipedia：下载维基百科数据\n- ./krull download-knowledge：下载开发者文档和其他知识资源\n\n## 应用场景\n\nKrull AI适用于多种场景：\n\n- 隐私敏感环境：医疗、法律、金融等行业，数据不能离开本地\n- 网络受限环境：野外作业、船舶、航空器、偏远地区\n- 成本优化：避免持续的API调用费用\n- 技术自主：减少对云服务商的依赖，确保服务的连续性\n- 开发测试：在本地快速验证AI应用原型，无需申请API密钥\n\n## 技术启示\n\nKrull AI项目展示了构建完整AI技术栈的可能性。它证明了一个完全自托管、离线可用的AI环境不再是遥不可及的梦想。通过精心选择和编排开源组件，配合针对性的优化和集成，开发者可以构建出媲美商业云服务的本地解决方案。\n\n项目的成功也得益于对开发者体验的重视——与Claude Code的集成不是简单的API兼容，而是对工作流、习惯、现有资产的全面尊重。这种"渐进式私有化"的策略，或许是推动AI基础设施去中心化的可行路径。\n\n## 结语\n\n在AI能力日益集中化的趋势下，Krull AI代表了一种不同的选择——自主、可控、离线可用。它不仅是一个技术项目，更是一种对技术主权的追求。对于那些重视数据隐私、需要在离线环境工作、或希望减少对云服务依赖的用户来说，Krull AI提供了一个功能完备、易于部署的解决方案。\n\n随着开源模型的不断进步和边缘计算能力的提升，类似的自托管AI技术栈将变得越来越实用。Krull AI的探索为这一趋势提供了宝贵的实践经验和技术参考。

Krull AI：完整的本地自托管AI技术栈\n\n自主可控的AI基础设施\n\n在云服务主导AI应用开发的今天，一个完全自托管、无需API密钥、甚至无需互联网连接的AI技术栈显得尤为珍贵。Krull AI正是这样一个项目——它的名字源于"Knowledge, Reasoning, and Unified Local Learning"，体现了构建本地化AI能力的核心理念。\n\n无论是出于数据隐私考虑、网络环境限制，还是对技术自主可控的追求，Krull AI都提供了一个令人信服的解决方案。它不仅仅是一个聊天机器人，而是一套完整的基础设施，涵盖了从模型推理到知识检索、从网络搜索到地图服务的全方位能力。\n\n架构概览：七大核心服务\n\nKrull AI采用微服务架构，通过Docker Compose编排七个核心组件：\n\n1. Open WebUI（端口3000）\n\n基于浏览器的聊天界面，支持RAG（检索增强生成）、工具调用和管道处理。这是用户与系统交互的主要入口，提供了类似ChatGPT的对话体验，但完全运行在本地。\n\n2. Ollama（内部服务）\n\nGPU加速的LLM推理引擎，负责模型的加载和推理。它支持多种开源模型，并能够充分利用NVIDIA GPU的计算能力。\n\n3. LiteLLM（端口4000）\n\nAPI网关服务，使Claude Code等外部工具能够与本地模型通信。这是Krull AI与现有开发工作流集成的关键桥梁——开发者可以继续使用熟悉的Claude Code界面，但背后的"大脑"换成了本地运行的开源模型。\n\n4. SearXNG（内部服务）\n\n元搜索引擎，聚合多个搜索引擎（Google、DuckDuckGo、Brave等）的结果。当系统需要获取实时信息时，SearXNG提供了去中心化的搜索能力，避免依赖单一搜索引擎。\n\n5. Martin（端口8070）\n\n离线地图瓦片服务器，支持PMTiles和MBTiles格式。这一组件使得系统能够在无网络环境下提供地图浏览、地理编码和路径规划能力，对于野外作业、应急响应等场景尤为实用。\n\n6. Photon（内部服务）\n\n离线地理编码和地点搜索服务。与Martin配合，实现了完整的地图功能栈，无需调用Google Maps等商业API。\n\n7. Kiwix（端口8090）\n\n离线维基百科和知识档案服务器。通过下载ZIM格式的离线数据库，系统可以在断网环境下访问海量知识内容，从百科全书到技术文档，从经典文学到学术论文。\n\n核心设计理念：与Claude Code的深度集成\n\nKrull AI的一个独特设计目标是与Claude Code的无缝集成。开发者无需改变使用习惯——原有的技能、钩子、CLAUDE.md文件和工作流都能继续工作，只是背后的模型从云端API切换到了本地推理。\n\n这种设计体现了对开发者工作流的深度尊重。Claude Code已成为许多开发者的日常工具，而Krull AI提供了一种"换芯不换壳"的私有化方案。通过LiteLLM的API网关，本地模型以兼容OpenAI API的格式暴露服务，Claude Code可以像连接OpenAI或Anthropic API一样连接本地模型。\n\n离线能力的全面覆盖\n\nKrull AI的真正实力在断网环境下才能充分展现。项目提供了丰富的离线数据下载工具：\n\n离线地图数据\n\n支持下载多种类型的地图数据：\n\n- 基础地图：OpenStreetMap矢量瓦片，包含道路、建筑、水域、土地利用等信息\n- 地形数据：全球高程数据，支持山体阴影、等高线和3D地形渲染\n- 海图：NOAA nautical charts，包含水深测量、浮标、航道、海底底质等专业航海信息\n- 航空图：FAA VFR Sectional Charts，包含机场、空域分类、导航辅助设施、障碍物等航空信息\n\n覆盖范围从美国各州到全球，数据量从几十MB到80GB不等，用户可根据需求灵活选择。\n\n离线知识库\n\n通过Kiwix支持多种知识资源的离线访问：\n\n- 维基百科：从精简版（无图片，约25GB）到完整版（含图片，约115GB），甚至可按主题下载（如医学专题约2GB）\n- 开发者文档：Python、JavaScript、TypeScript、Node.js、Git、Docker、Bash等开发必备文档\n- Stack Exchange：Stack Overflow、Server Fault、Super User等技术问答社区内容\n- 古腾堡计划：6万多本免费电子书，按小说、科学、STEM等分类组织\n\n离线搜索能力\n\n即使在没有互联网的情况下，SearXNG仍可搜索已下载的本地知识库，实现离线环境下的信息检索。\n\n模型管理与优化\n\nKrull AI对模型管理进行了精心设计，特别是针对与Claude Code的兼容性：\n\n推荐的Qwen3.5模型\n\n项目推荐使用frob/qwen3.5-instruct系列模型，原因如下：\n\n- 工具调用兼容性：该模型变体能够生成符合Anthropic风格的tool_use代码块，这是Claude Code正确解析工具调用所必需的。相比之下，qwen2.5-coder模型将工具调用输出为纯JSON文本，会导致工具调用失败。\n\n- 思考模式优化：frob/qwen3.5-instruct是Qwen3.5的变体，禁用了思考模式，响应速度更快，同时保持了相同的模型权重和输出质量。\n\n参数调优\n\n项目为不同场景提供了预设的参数配置：\n\n- 通用场景：temperature 0.7，top_p 0.8，平衡创造性和一致性\n- 编程场景：可通过环境变量覆盖为temperature 0.6，降低随机性，提高代码准确性\n\n模型选择指南\n\n根据GPU显存容量，用户可选择不同规模的模型：\n\n| 模型 | 显存需求 | 适用场景 |\n|------|----------|----------|\n| qwen3.5-instruct:4b | ~3GB | 快速响应，轻量硬件 |\n| qwen3.5-instruct:9b | ~6GB | 推荐配置，编程+工具调用 |\n| qwen3.5-instruct:27b | ~16GB | 最佳质量，需要高端GPU |\n\n智能过滤器与增强功能\n\nKrull AI不仅仅是各组件的简单堆砌，还通过智能过滤器增强了本地模型的能力：\n\n- 上下文管理：优化长对话的上下文窗口使用，避免早期信息丢失\n- 自动网络搜索：在需要时自动触发SearXNG搜索，补充模型知识\n- 离线知识注入：将Kiwix中的相关知识自动注入提示词，增强回答准确性\n- 计划模式保护：在复杂任务规划时提供引导，防止模型偏离目标\n\n这些过滤器通过./krull setup命令一键安装，显著提升了本地模型的实用性和可靠性。\n\n部署与使用\n\nKrull AI的部署流程设计得尽可能简单：\n\nbash\ngit clone git@github.com:odysseyalive/krull-ai.git\ncd krull-ai\n./krull start\n\n\n首次运行会拉取Docker镜像（约10GB）并下载维基百科入门数据（约5MB），耗时几分钟。之后，系统提供了一系列管理命令：\n\n- ./krull pull-model：下载和管理模型\n- ./krull download-maps：下载离线地图数据\n- ./krull download-wikipedia：下载维基百科数据\n- ./krull download-knowledge：下载开发者文档和其他知识资源\n\n应用场景\n\nKrull AI适用于多种场景：\n\n- 隐私敏感环境：医疗、法律、金融等行业，数据不能离开本地\n- 网络受限环境：野外作业、船舶、航空器、偏远地区\n- 成本优化：避免持续的API调用费用\n- 技术自主：减少对云服务商的依赖，确保服务的连续性\n- 开发测试：在本地快速验证AI应用原型，无需申请API密钥\n\n技术启示\n\nKrull AI项目展示了构建完整AI技术栈的可能性。它证明了一个完全自托管、离线可用的AI环境不再是遥不可及的梦想。通过精心选择和编排开源组件，配合针对性的优化和集成，开发者可以构建出媲美商业云服务的本地解决方案。\n\n项目的成功也得益于对开发者体验的重视——与Claude Code的集成不是简单的API兼容，而是对工作流、习惯、现有资产的全面尊重。这种"渐进式私有化"的策略，或许是推动AI基础设施去中心化的可行路径。\n\n结语\n\n在AI能力日益集中化的趋势下，Krull AI代表了一种不同的选择——自主、可控、离线可用。它不仅是一个技术项目，更是一种对技术主权的追求。对于那些重视数据隐私、需要在离线环境工作、或希望减少对云服务依赖的用户来说，Krull AI提供了一个功能完备、易于部署的解决方案。\n\n随着开源模型的不断进步和边缘计算能力的提升，类似的自托管AI技术栈将变得越来越实用。Krull AI的探索为这一趋势提供了宝贵的实践经验和技术参考。