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

贡献

欢迎本地模型和推理优化相关的贡献！

# 克隆仓库
git clone https://github.com/maxclaw/maxclaw.git

# 构建
make build

# 运行测试
make test

# 性能测试
make benchmark

许可证

MIT License - 详见 LICENSE

访问 GitHub 仓库 →

MaxClaw - 本地模型优先

核心特性

本地模型优先

离线可用

混合推理

硬件加速

快速开始

系统要求

安装

配置

启动

技术架构

llama.cpp 集成

智能路由

模型管理

支持的模型

推荐模型

量化版本

功能特性

GPU 加速

批处理推理

流式输出

适用场景

隐私敏感

离线环境

成本优化

性能对比

与其他版本对比

vs 官方版

vs ZeroClaw

vs PicoClaw

常见问题

模型下载慢

内存不足

GPU 不工作

相关链接

贡献

许可证