MaxClaw - 本地模型优先
约 1528 字大约 5 分钟
2026-03-07
本地模型优先版 - 内嵌 llama.cpp bindings,Local-First 架构,优先使用本地模型,离线断网也能使用。
核心特性
本地模型优先
- 内嵌 llama.cpp 引擎
- 支持 GGUF 格式模型
- 优先本地推理
- 云端模型作为备选
离线可用
- 完全离线运行
- 无需互联网连接
- 数据不出本地
- 隐私完全保护
混合推理
- 本地模型处理简单任务
- 云端模型处理复杂任务
- 智能路由选择
- 成本优化
硬件加速
- CPU 推理优化
- GPU 加速支持 (CUDA/Metal)
- 量化模型支持
- 内存优化
快速开始
系统要求
- 8GB+ RAM (推荐 16GB)
- 10GB+ 磁盘空间
- CPU: AVX2 支持
- GPU: 可选 (CUDA/Metal)
安装
# 克隆仓库
git clone https://github.com/maxclaw/maxclaw.git
cd maxclaw
# 安装依赖
go mod download
# 构建(自动编译 llama.cpp)
make build
# 下载模型
./maxclaw download-model llama-3-8b-instruct配置
创建 config.yaml:
# 模型配置
models:
local:
# 本地模型路径
path: ./models/llama-3-8b-instruct.gguf
# 上下文长度
context_size: 4096
# 线程数
threads: 8
# GPU 层数 (0 = CPU only)
gpu_layers: 0
cloud:
# 云端模型作为备选
provider: anthropic
model: claude-3-5-sonnet-20241022
api_key: ${ANTHROPIC_API_KEY}
# 路由策略
routing:
# 优先使用本地模型
prefer_local: true
# 本地模型失败时使用云端
fallback_to_cloud: true
# 复杂任务阈值
complexity_threshold: 0.7启动
# 启动服务
./maxclaw start
# 纯本地模式(不使用云端)
./maxclaw start --local-only
# 交互模式
./maxclaw chat技术架构
llama.cpp 集成
package llm
/*
#cgo LDFLAGS: -L./lib -lllama -lm -lstdc++
#include "llama.h"
*/
import "C"
import "unsafe"
type LlamaModel struct {
model *C.struct_llama_model
ctx *C.struct_llama_context
params C.struct_llama_context_params
}
func NewLlamaModel(modelPath string, params ModelParams) (*LlamaModel, error) {
// 初始化 llama.cpp
C.llama_backend_init(false)
// 加载模型
cModelPath := C.CString(modelPath)
defer C.free(unsafe.Pointer(cModelPath))
model := C.llama_load_model_from_file(cModelPath, C.struct_llama_model_params{})
if model == nil {
return nil, errors.New("failed to load model")
}
// 创建上下文
ctxParams := C.llama_context_default_params()
ctxParams.n_ctx = C.uint32_t(params.ContextSize)
ctxParams.n_threads = C.int32_t(params.Threads)
ctxParams.n_gpu_layers = C.int32_t(params.GPULayers)
ctx := C.llama_new_context_with_model(model, ctxParams)
return &LlamaModel{
model: model,
ctx: ctx,
params: ctxParams,
}, nil
}
func (lm *LlamaModel) Generate(prompt string, maxTokens int) (string, error) {
// Tokenize
tokens := lm.tokenize(prompt)
// Generate
var result []C.llama_token
for i := 0; i < maxTokens; i++ {
token := C.llama_sample_token(lm.ctx, nil)
if token == C.llama_token_eos(lm.model) {
break
}
result = append(result, token)
C.llama_decode(lm.ctx, C.llama_batch_get_one(&token, 1, 0, 0))
}
// Detokenize
return lm.detokenize(result), nil
}智能路由
type ModelRouter struct {
localModel *LlamaModel
cloudModel *ClaudeClient
config RouterConfig
}
func (r *ModelRouter) Route(prompt string) (string, error) {
// 分析任务复杂度
complexity := r.analyzeComplexity(prompt)
// 决定使用哪个模型
if r.config.PreferLocal && complexity < r.config.ComplexityThreshold {
// 使用本地模型
response, err := r.localModel.Generate(prompt, 1024)
if err == nil {
return response, nil
}
// 本地失败,回退到云端
if r.config.FallbackToCloud {
return r.cloudModel.Generate(prompt)
}
return "", err
}
// 使用云端模型
return r.cloudModel.Generate(prompt)
}
func (r *ModelRouter) analyzeComplexity(prompt string) float64 {
// 简单的复杂度评估
factors := []float64{
float64(len(prompt)) / 1000.0, // 长度
float64(strings.Count(prompt, "?")) / 5.0, // 问题数量
r.detectCodeRequest(prompt), // 是否涉及代码
r.detectReasoningRequest(prompt), // 是否需要推理
}
var sum float64
for _, f := range factors {
sum += f
}
return math.Min(sum / float64(len(factors)), 1.0)
}模型管理
type ModelManager struct {
modelsDir string
}
func (mm *ModelManager) DownloadModel(modelName string) error {
// 从 Hugging Face 下载
url := fmt.Sprintf("https://huggingface.co/%s/resolve/main/model.gguf", modelName)
resp, err := http.Get(url)
if err != nil {
return err
}
defer resp.Body.Close()
// 保存到本地
filePath := filepath.Join(mm.modelsDir, modelName+".gguf")
out, err := os.Create(filePath)
if err != nil {
return err
}
defer out.Close()
// 显示进度
bar := progressbar.DefaultBytes(resp.ContentLength, "Downloading")
_, err = io.Copy(io.MultiWriter(out, bar), resp.Body)
return err
}
func (mm *ModelManager) ListModels() ([]ModelInfo, error) {
files, err := os.ReadDir(mm.modelsDir)
if err != nil {
return nil, err
}
var models []ModelInfo
for _, file := range files {
if strings.HasSuffix(file.Name(), ".gguf") {
info, _ := file.Info()
models = append(models, ModelInfo{
Name: strings.TrimSuffix(file.Name(), ".gguf"),
Size: info.Size(),
Path: filepath.Join(mm.modelsDir, file.Name()),
})
}
}
return models, nil
}支持的模型
推荐模型
| 模型 | 大小 | 内存需求 | 性能 |
|---|---|---|---|
| Llama 3 8B Instruct | 4.7GB | 8GB | 优秀 |
| Mistral 7B Instruct | 4.1GB | 6GB | 优秀 |
| Phi-3 Mini | 2.3GB | 4GB | 良好 |
| Qwen 2 7B | 4.4GB | 8GB | 优秀 |
量化版本
# Q4_K_M - 推荐,平衡质量和速度
./maxclaw download-model llama-3-8b-instruct-q4
# Q5_K_M - 更高质量
./maxclaw download-model llama-3-8b-instruct-q5
# Q8_0 - 最高质量
./maxclaw download-model llama-3-8b-instruct-q8功能特性
GPU 加速
# CUDA (NVIDIA)
models:
local:
gpu_layers: 35 # 将层卸载到 GPU
# Metal (Apple Silicon)
models:
local:
gpu_layers: 35
metal: true批处理推理
func (lm *LlamaModel) BatchGenerate(prompts []string) ([]string, error) {
var results []string
// 批量处理
batch := C.llama_batch_init(C.int32_t(len(prompts)), 0, 1)
defer C.llama_batch_free(batch)
for _, prompt := range prompts {
tokens := lm.tokenize(prompt)
// 添加到批次
for _, token := range tokens {
C.llama_batch_add(&batch, token, 0, nil, false)
}
}
// 批量推理
C.llama_decode(lm.ctx, batch)
// 收集结果
for range prompts {
result := lm.sampleAndGenerate()
results = append(results, result)
}
return results, nil
}流式输出
func (lm *LlamaModel) StreamGenerate(prompt string, callback func(string)) error {
tokens := lm.tokenize(prompt)
for {
token := C.llama_sample_token(lm.ctx, nil)
if token == C.llama_token_eos(lm.model) {
break
}
// 实时回调
text := lm.detokenize([]C.llama_token{token})
callback(text)
C.llama_decode(lm.ctx, C.llama_batch_get_one(&token, 1, 0, 0))
}
return nil
}适用场景
隐私敏感
- 处理敏感数据
- 企业内网部署
- 数据不能上云
离线环境
- 无互联网连接
- 飞机、火车上使用
- 军事、政府场景
成本优化
- 减少 API 调用
- 本地处理简单任务
- 降低运营成本
性能对比
| 场景 | 本地模型 | 云端模型 |
|---|---|---|
| 简单问答 | 2-5s | 1-2s |
| 代码生成 | 5-10s | 2-4s |
| 复杂推理 | 10-20s | 3-6s |
| 成本 | $0 | $0.01-0.10 |
与其他版本对比
vs 官方版
- 官方版依赖云端 API,MaxClaw 可离线
- 官方版无本地模型,MaxClaw 内嵌 llama.cpp
- MaxClaw 是官方版的离线增强
vs ZeroClaw
- ZeroClaw 追求性能,MaxClaw 追求离线能力
- 两者都是高性能实现
- MaxClaw 有本地模型支持
vs PicoClaw
- PicoClaw 轻量部署,MaxClaw 功能完整
- MaxClaw 需要更多资源
- 应用场景不同
常见问题
模型下载慢
# 使用镜像站
export HF_ENDPOINT=https://hf-mirror.com
./maxclaw download-model llama-3-8b-instruct内存不足
# 使用更小的模型或更激进的量化
models:
local:
path: ./models/phi-3-mini-q4.gguf
context_size: 2048 # 减小上下文GPU 不工作
# 检查 CUDA
nvidia-smi
# 重新编译启用 CUDA
make clean
make LLAMA_CUDA=1相关链接
- GitHub: maxclaw/maxclaw
- llama.cpp: ggerganov/llama.cpp
- 模型下载: Hugging Face
- 问题反馈: Issues
贡献
欢迎本地模型和推理优化相关的贡献!
# 克隆仓库
git clone https://github.com/maxclaw/maxclaw.git
# 构建
make build
# 运行测试
make test
# 性能测试
make benchmark许可证
MIT License - 详见 LICENSE