本地模型尝试

记录一下在 Windows 环境下配置 llama.cpp 的全过程，包括编译、启动参数调优、网络排查以及接入开发工具链的细节。

1. 编译与环境

编译踩坑记录

OpenSSL 找不到: 产生的 Warning 可以忽略。本地和局域网连接不需要 HTTPS。
WebUI 找不到: 产生的 Error 可以通过禁用 WebUI 解决。

编译步骤

cd ~/Code/External/llama.cpp
rm -rf build
cmake -B build -DGGML_CUDA=ON -DLLAMA_BUILD_WEBUI=OFF
cmake --build build -j

开启服务

./build/bin/llama-server -m xxx.gguf --host 0.0.0.0 --port 8080

2. 模型选择与下载

我的windows环境是 RTX 4080 (16GB 显存)。

实测模型对比

Qwen3.6-27B (IQ4_XS): 可以用, 逻辑遵循和工具调用上都正常。
Qwen3-Coder-30B-A3B (IQ4_XS): 实测效果不好，很笨。

下载方法

从 Hugging Face 下载 GGUF 格式的模型, 用的unsloth版本.

支持 wget 直接下载。
使用 huggingface-cli，支持 文件校验 和 断点续传。

使用 wget 下载示例：

wget https://huggingface.co/unsloth/Qwen3-Coder-30B-A3B-Instruct-GGUF/resolve/main/Qwen3-Coder-30B-A3B-Instruct-IQ4_XS.gguf

使用 huggingface-cli 下载示例：

# 下载指定模型 (示例：Qwen 27B 的 IQ4_XS 版本)
huggingface-cli download Qwen/Qwen2.5-Coder-32B-Instruct-GGUF \
    Qwen2.5-Coder-32B-Instruct-IQ4_XS.gguf \
    --local-dir models --local-dir-use-symlinks False

3. 服务启动与参数

启动 llama-server, 我使用的启动命令如下，针对 Qwen-27B 级别的模型进行了优化：

./build/bin/llama-server \
  -m /models/qwen.gguf \
  --host 0.0.0.0 \ #允许监听局域网内所有接口，以便我的 Mac 访问
  --port 8080 \ # 端口号, 记得要设置防火墙放行
  -ngl 999 \ #指定卸载到 GPU 的层数, 999意思就是强制将所有模型层卸载至显存, 纯gpu推理
  -c 65536 \ #设置上下文窗口, 64K context或者32k
  -np 1\ #并行处理的序列数（Number of Parallel Sequences), 我用Qwen-27B基本把显存占满了, 只能设置1
  -b 2048 \ #Batch Size, gpu最大接收token数
  -ub 512 \ #UBatch Size, 切分size, 每次送到gpu的size, 控制显存占用峰值
  --flash-attn on \ #降低显存占用并提升注意力机制计算速度
  --metriccs \  # 启用 Prometheus 格式的监控指标, 可以看http://localhost:8080/metrics 监控请求延迟、token 生成速度、缓存命中率、显存占用等
  --cache-type-k q4_0 \  #KV Cache 的量化类型
  --cache-type-v q4_0 \
  #-- jinja \ # jinja模版解析prompt, 让toolcall 更稳定. 开不开好像区别不大
  --resoning-fomat none #并不关闭推理，只影响 API 输出
  -reasoning off \      # 禁用 reasoning 功能
  --reasoning-budget 0 \ # 将推理预算设为 0

模板残留：输出中仍有空 <think></think> 标签是由于 --jinja 强制套用了 GGUF 内嵌模板（Qwen 模板写死了该占位符）。我最后也没通过参数解决这个空<think></think> 的问题.

4. 远程访问与网络配置

局域网连通性排查

在 Mac 访问 Windows 端口失败时，按以下步骤排查：

Ping 测试: ping 192.168.1.2 成功，确认基础链路正常。
端口探测: 运行 nc -zv 192.168.1.2 8080
- 返回 Operation timed out。ICMP通但TCP不通，是典型的防火墙丢弃包（Drop）特征。
  - 解决: 在powershell里以管理员权限设置放行端口: New-NetFirewallRule -DisplayName "llama-server" -Direction Inbound -LocalPort 8080 -Protocol TCP -Action Allow
- 返回 Connection refused. 说明防火墙已放行，ssh没启动, 去wsl2拉起ssh服务.
  - 解决: sudo service ssh start

模型调用测试

# 测试模型列表
curl http://localhost:8080/v1/models

# 测试对话接口
curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "write a python quicksort"
      }
    ]
  }'

5. CLI 工具链集成

将本地算力接入了 pi 和 claude 等开发工具。

Claude Code 精简启动

export ANTHROPIC_BASE_URL=http://localhost:8080
export ANTHROPIC_AUTH_TOKEN=dummy
export ANTHROPIC_API_KEY=dummy
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1

Claude Code 默认启动会携带约 28k tokens 的负载，我采用极简模式启动以确保本地模型不会因为上下文过载而“变笨”：

# 精简模式：跳过 28k tokens 的冗余加载，仅保留核心工具
claude --model local-coder \
    --bare \
    --tools 'Read,Edit,Write,Bash,Grep,Glob,LS' \
    --disable-slash-commands

但是这样用不了skills了, 我尝试用extension的方式加载, 没成功

Pi (AI Coding Assistant)

在 ~/.pi/agent/models.json 中将 API 类型设为 openai-completions。这种模式会通过 System Prompt 注入工具定义，就不用更复杂的协议了。