Neurons是一个从零开始构建的大语言模型推理引擎，不依赖llama.cpp或Ollama等封装库，直接使用Metal/MLX、cuBLAS和Flash Attention实现Transformer前向传播。

Neurons：从零构建的LLM推理引擎与全栈聊天应用\n\n## 项目概述\n\nNeurons是一个从零开始构建的大语言模型推理引擎和聊天应用。与大多数使用llama.cpp或Ollama等封装库的项目不同，Neurons直接使用Metal/MLX、cuBLAS和Flash Attention等底层技术，从第一性原理实现Transformer的前向传播过程。\n\n这个项目的核心目标是帮助开发者真正理解大语言模型在硬件层面的工作原理，而不是仅仅调用高级API。\n\n## 架构设计\n\nNeurons采用清晰的分层架构，将计算、服务和界面三个层面完全解耦：\n\n### 1. 计算层（compute/）\n\n这是用C++23编写的推理库，实现了Transformer的核心组件：\n\n- 量化矩阵乘法：支持高效的低精度计算\n- RoPE（旋转位置编码）：处理序列位置信息\n- RMSNorm：稳定的层归一化实现\n- KV缓存：加速多轮对话的关键优化\n- 采样策略：支持temperature、top-p、top-k等参数\n\n计算层采用插件式后端设计（ComputeBackend接口），目前支持MLX后端（Apple Silicon），CUDA和ROCm后端正在开发中。\n\n### 2. 服务层（service/）\n\n服务层提供两种接口：\n\n- gRPC推理服务器：支持分布式部署，可在局域网内的任何机器上运行\n- OpenAI兼容的HTTP端点：端口8080，可直接对接Cursor、Continue.dev等工具\n\n这种设计使得Neurons既可以作为本地单机应用运行，也可以部署为网络服务。\n\n### 3. 界面层\n\nNeurons提供了三种交互方式：\n\n| 功能 | GUI | CLI | gRPC |\n|------|-----|-----|------|\n| 多轮对话 | ✅ | ✅ | ✅ |\n| 流式生成 | ✅ | ✅ | ✅ |\n| 实时token速度统计 | ✅ | ✅ | ✅ |\n| 模型下载与管理 | ✅ | ✅ | ✅ |\n| HuggingFace认证 | ✅ | ✅ | ✅ |\n| 采样参数调整 | ✅ | ✅ | ✅ |\n| 多节点管理 | ✅ | ✅ | — |\n| OpenAI兼容HTTP端点 | — | ✅ | — |\n\n## 支持的模型家族\n\nNeurons目前支持多种主流模型架构：\n\n- Llama 2/3系列：包括TinyLlama等变体\n- Mistral系列：7B指令模型\n- Qwen2/Qwen2.5系列：阿里巴巴的通义千问模型\n- Gemma系列：Google的轻量级模型\n\n所有模型都直接从HuggingFace下载MLX量化版本，支持4bit量化，大幅降低内存占用。\n\n## 技术实现细节\n\n### 跨平台架构\n\nNeurons的GUI使用Flutter开发，支持macOS、Windows、Linux和移动端。关键在于：\n\n- 本地运行：通过dart:ffi直接调用libneurons_core.dylib\n- 远程连接：通过gRPC与远程节点通信\n- 统一接口：NeuronsClient抽象层屏蔽了本地和远程的差异\n\n### 模型加载流程\n\n\nGUI/CLI → NeuronsClient → libneurons_core → LanguageModel → ComputeBackend\n\n\n这种设计允许：\n- 添加新模型家族：只需实现LanguageModel接口\n- 添加新后端：只需实现ComputeBackend接口\n- 扩展CLI命令：在cli/src/cli/commands/添加新命令\n\n## 多节点部署\n\nNeurons支持将多台机器连接为推理集群：\n\nbash\n# 在远程服务器上启动服务\nneurons server --grpc-port 50051 --http-port 8080\n\n# 在本地添加节点\nneurons node add my-server grpc://192.168.1.10:50051\nneurons node use my-server\n\n\nGUI的Nodes标签页可以直观管理多个远程节点，实现负载均衡和故障转移。\n\n## 开发路线图\n\n| 阶段 | 状态 | 描述 |\n|------|------|------|\n| A-E | ✅ | MLX后端、KV缓存、采样、多模型支持 |\n| F | ✅ | 模型家族扩展（fp16/bf16、Gemma3、Qwen2.5） |\n| G-I | ✅ | gRPC服务、Flutter GUI、CLI、OpenAI HTTP端点 |\n| J | 🚧 | 文件附件+RAG（向量嵌入、sqlite-vec） |\n| K | 🚧 | 多节点路由、投机解码、故障转移 |\n| L | 🚧 | MCP客户端+工具使用 |\n| B/C | 🚧 | CUDA（cuBLAS+Flash Attention）和ROCm后端 |\n\n## 为什么值得关注\n\n1. 教育价值：对于想深入理解LLM推理原理的开发者，Neurons提供了比阅读论文更直观的学习路径\n\n2. 工程实践：展示了如何将C++推理核心、Flutter GUI和gRPC服务整合为一个完整产品\n\n3. 开源友好：MIT许可证，代码结构清晰，易于扩展和修改\n\n4. 实用价值：虽然还在开发中，但已经可以替代Ollama等工具进行本地LLM推理\n\n## 快速开始\n\nbash\n# 克隆仓库\ngit clone https://github.com/dexwritescode/neurons.git\ncd neurons\n\n# 构建所有组件\nmake all\n\n# 搜索并下载模型\n./build/bin/cli search \"qwen 3b\"\n./build/bin/cli download mlx-community/Qwen2.5-3B-Instruct-4bit\n\n# 开始聊天\n./build/bin/cli chat mlx-community/Qwen2.5-3B-Instruct-4bit\n\n\n## 总结\n\nNeurons代表了一种"从第一性原理出发"的工程哲学。在LLM工具链日益复杂的今天，它提供了一个回归本质的选择——不依赖黑盒封装，而是亲手构建每一个组件。\n\n对于想要真正理解大模型工作原理的开发者，或者需要高度定制化推理流程的高级用户，Neurons是一个值得深入研究的优秀开源项目。

Neurons：从零构建的LLM推理引擎与全栈聊天应用\n\n项目概述\n\nNeurons是一个从零开始构建的大语言模型推理引擎和聊天应用。与大多数使用llama.cpp或Ollama等封装库的项目不同，Neurons直接使用Metal/MLX、cuBLAS和Flash Attention等底层技术，从第一性原理实现Transformer的前向传播过程。\n\n这个项目的核心目标是帮助开发者真正理解大语言模型在硬件层面的工作原理，而不是仅仅调用高级API。\n\n架构设计\n\nNeurons采用清晰的分层架构，将计算、服务和界面三个层面完全解耦：\n\n1. 计算层（compute/）\n\n这是用C++23编写的推理库，实现了Transformer的核心组件：\n\n- 量化矩阵乘法：支持高效的低精度计算\n- RoPE（旋转位置编码）：处理序列位置信息\n- RMSNorm：稳定的层归一化实现\n- KV缓存：加速多轮对话的关键优化\n- 采样策略：支持temperature、top-p、top-k等参数\n\n计算层采用插件式后端设计（ComputeBackend接口），目前支持MLX后端（Apple Silicon），CUDA和ROCm后端正在开发中。\n\n2. 服务层（service/）\n\n服务层提供两种接口：\n\n- gRPC推理服务器：支持分布式部署，可在局域网内的任何机器上运行\n- OpenAI兼容的HTTP端点：端口8080，可直接对接Cursor、Continue.dev等工具\n\n这种设计使得Neurons既可以作为本地单机应用运行，也可以部署为网络服务。\n\n3. 界面层\n\nNeurons提供了三种交互方式：\n\n| 功能 | GUI | CLI | gRPC |\n|------|-----|-----|------|\n| 多轮对话 | ✅ | ✅ | ✅ |\n| 流式生成 | ✅ | ✅ | ✅ |\n| 实时token速度统计 | ✅ | ✅ | ✅ |\n| 模型下载与管理 | ✅ | ✅ | ✅ |\n| HuggingFace认证 | ✅ | ✅ | ✅ |\n| 采样参数调整 | ✅ | ✅ | ✅ |\n| 多节点管理 | ✅ | ✅ | — |\n| OpenAI兼容HTTP端点 | — | ✅ | — |\n\n支持的模型家族\n\nNeurons目前支持多种主流模型架构：\n\n- Llama 2/3系列：包括TinyLlama等变体\n- Mistral系列：7B指令模型\n- Qwen2/Qwen2.5系列：阿里巴巴的通义千问模型\n- Gemma系列：Google的轻量级模型\n\n所有模型都直接从HuggingFace下载MLX量化版本，支持4bit量化，大幅降低内存占用。\n\n技术实现细节\n\n跨平台架构\n\nNeurons的GUI使用Flutter开发，支持macOS、Windows、Linux和移动端。关键在于：\n\n- 本地运行：通过dart:ffi直接调用libneurons_core.dylib\n- 远程连接：通过gRPC与远程节点通信\n- 统一接口：NeuronsClient抽象层屏蔽了本地和远程的差异\n\n模型加载流程\n\n\nGUI/CLI → NeuronsClient → libneurons_core → LanguageModel → ComputeBackend\n\n\n这种设计允许：\n- 添加新模型家族：只需实现LanguageModel接口\n- 添加新后端：只需实现ComputeBackend接口\n- 扩展CLI命令：在cli/src/cli/commands/添加新命令\n\n多节点部署\n\nNeurons支持将多台机器连接为推理集群：\n\nbash\n在远程服务器上启动服务\nneurons server --grpc-port 50051 --http-port 8080\n\n在本地添加节点\nneurons node add my-server grpc://192.168.1.10:50051\nneurons node use my-server\n\n\nGUI的Nodes标签页可以直观管理多个远程节点，实现负载均衡和故障转移。\n\n开发路线图\n\n| 阶段 | 状态 | 描述 |\n|------|------|------|\n| A-E | ✅ | MLX后端、KV缓存、采样、多模型支持 |\n| F | ✅ | 模型家族扩展（fp16/bf16、Gemma3、Qwen2.5） |\n| G-I | ✅ | gRPC服务、Flutter GUI、CLI、OpenAI HTTP端点 |\n| J | 🚧 | 文件附件+RAG（向量嵌入、sqlite-vec） |\n| K | 🚧 | 多节点路由、投机解码、故障转移 |\n| L | 🚧 | MCP客户端+工具使用 |\n| B/C | 🚧 | CUDA（cuBLAS+Flash Attention）和ROCm后端 |\n\n为什么值得关注\n\n1. 教育价值：对于想深入理解LLM推理原理的开发者，Neurons提供了比阅读论文更直观的学习路径\n\n2. 工程实践：展示了如何将C++推理核心、Flutter GUI和gRPC服务整合为一个完整产品\n\n3. 开源友好：MIT许可证，代码结构清晰，易于扩展和修改\n\n4. 实用价值：虽然还在开发中，但已经可以替代Ollama等工具进行本地LLM推理\n\n快速开始\n\nbash\n克隆仓库\ngit clone https://github.com/dexwritescode/neurons.git\ncd neurons\n\n构建所有组件\nmake all\n\n搜索并下载模型\n./build/bin/cli search \"qwen 3b\"\n./build/bin/cli download mlx-community/Qwen2.5-3B-Instruct-4bit\n\n开始聊天\n./build/bin/cli chat mlx-community/Qwen2.5-3B-Instruct-4bit\n\n\n总结\n\nNeurons代表了一种"从第一性原理出发"的工程哲学。在LLM工具链日益复杂的今天，它提供了一个回归本质的选择——不依赖黑盒封装，而是亲手构建每一个组件。\n\n对于想要真正理解大模型工作原理的开发者，或者需要高度定制化推理流程的高级用户，Neurons是一个值得深入研究的优秀开源项目。