本地化 AI 编程助手：使用 Ollama + Qwen3.8:27b + Claude Code / Codex

Hi20240217

367人浏览 · 2026-08-17 20:25:51

Hi20240217 · 2026-08-17 20:25:51 发布

本地化 AI 编程助手：使用 Ollama + Qwen3.8:27b + Claude Code / Codex

本指南将带你从源码编译并部署一个完全本地化的大语言模型编码环境。我们使用：

Ollama：本地大模型运行框架，负责加载和推理模型。
Qwen3.8:27b：阿里通义千问系列开源模型，擅长代码生成与理解。
Claude Code：Anthropic 官方命令行 AI 编程助手，可通过环境变量指向本地服务。
Codex CLI：OpenAI 官方命令行编程代理，同样可配置为使用本地模型。

通过这套方案，你可以在内网或离线环境中使用强大的 AI 编码能力，且无需将代码上传到外部云服务，保障数据隐私与安全。

一、背景介绍

为什么从源码编译 Ollama？

官方预编译的 Ollama 二进制文件通常为了兼容性，会包含多种 CPU 指令集变体，但可能未针对你的 GPU 计算能力（CUDA 架构）进行优化。从源码编译可以：

只为当前 GPU 架构编译 CUDA kernel，提升推理效率；
关闭不必要的 CPU 变体，缩短编译时间；
获得最新或特定版本的功能

为什么用本地模型？

隐私安全：代码不会离开你的服务器。
低成本：无需按 token 付费，只需承担硬件和电费。
可控性：可自由调整上下文长度、量化方式、并发数等。
离线可用：不依赖互联网连接。

适用人群

需要在公司内网部署 AI 编程助手的开发者或运维人员。
希望完全掌控模型和数据的技术爱好者。
对 GPU 推理性能调优感兴趣的学习者。

二、前置条件

在开始之前，请确保你具备以下环境：

项目	要求
操作系统	Ubuntu 20.04/22.04/24.04（或其他 Debian 系，命令略有差异）
GPU	NVIDIA 显卡，建议显存 ≥ 24GB（对于 27B 模型，若使用 q8 量化并开启 49k 上下文，可能需要更大显存，如 32GB 或 48GB）
驱动	已安装 NVIDIA 驱动，`nvidia-smi` 可正常显示
CUDA Toolkit	已安装，`nvcc --version` 可正常显示（推荐 CUDA 12.x）
内存	≥ 32GB（编译需要较多内存）
磁盘	至少 80GB 可用空间（用于模型存储、编译中间文件）

检查 GPU 计算能力

编译时需要指定 CUDA 架构（如 86 代表 Ampere，即 RTX 30 系列）。运行以下命令查询你的 GPU 计算能力：

nvidia-smi --query-gpu=name,compute_cap --format=csv

输出示例：

name, compute_cap
NVIDIA GeForce RTX 3090, 8.6

8.6 对应的 CMake 参数为 -DCMAKE_CUDA_ARCHITECTURES=86。请根据你的实际情况调整（常见映射：7.5 → 75，8.0 → 80，8.6 → 86，8.9 → 89，9.0 → 90）。

如果尚未安装 CUDA Toolkit，请参考 NVIDIA 官方文档进行安装，并确保 nvcc 在 /usr/local/cuda/bin/nvcc 或已加入 PATH。

三、详细操作步骤

第 1 步：创建模型存储目录

Ollama 默认将模型存放在用户主目录下，但可能空间不足或你需要集中管理。这里我们自定义模型存储路径：

# 创建一个专门存放模型的目录
mkdir ollama_models
cd ollama_models

# 将当前目录设置为 OLLAMA_MODELS 环境变量（仅当前终端会话有效）
export OLLAMA_MODELS=$PWD
cd ..

说明：OLLAMA_MODELS 决定模型权重保存的位置。建议放在磁盘空间较大的分区。如果希望永久生效，可将 export OLLAMA_MODELS=/path/to/ollama_models 写入 ~/.bashrc 或 ~/.zshrc。

第 2 步：安装 Go

Ollama 使用 Go 语言编写，编译需要 Go 1.22 或更高版本。如果系统已安装合适版本，可跳过此步。

# 下载 Go 1.22.3（可根据需要到 https://go.dev/dl/ 获取更新版本）
wget https://go.dev/dl/go1.22.3.linux-amd64.tar.gz

# 解压到 /usr/local
sudo tar -C /usr/local -xzf go1.22.3.linux-amd64.tar.gz

# 将 Go 添加到 PATH（临时生效）
export PATH=$PATH:/usr/local/go/bin

# 建议写入 ~/.bashrc 以便长期使用
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
source ~/.bashrc

# 验证安装
go version

第 3 步：下载 Ollama 源码并切换版本

git clone https://github.com/ollama/ollama.git
cd ollama

# 切换到经过测试的特定版本
git checkout v0.32.14-rc0

第 4 步：安装 GCC 12

编译 Ollama 和 CUDA kernel 需要较新的 C++ 编译器。Ubuntu 默认的 GCC 可能版本较旧，建议升级到 GCC 12。

# 添加 toolchain 测试源
sudo add-apt-repository ppa:ubuntu-toolchain-r/test -y
sudo apt update

# 安装 GCC 12 和 G++ 12
sudo apt install gcc-12 g++-12 -y

# 将 GCC 12 设置为系统默认编译器
sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-12 120 --slave /usr/bin/g++ g++ /usr/bin/g++-12
sudo update-alternatives --config gcc

执行最后一条命令后，选择与 /usr/bin/gcc-12 对应的编号，回车确认。

第 5 步：编译 Ollama（启用 CUDA）

首先确保 CUDA 编译器路径正确。如果 nvcc 不在 /usr/local/cuda/bin/nvcc，请修改以下命令中的路径。

# 设置 CUDA 编译器路径（可选，若已在 PATH 中可省略）
export CUDACXX=/usr/local/cuda/bin/nvcc

# 关闭 CPU 全指令集变体编译，加快速度并减小二进制体积
sed -i 's/-DGGML_CPU_ALL_VARIANTS=ON/-DGGML_CPU_ALL_VARIANTS=OFF/g' cmake/local.cmake

# 配置 CMake 构建
cmake -B build \
  -DGGML_CUDA=ON \
  -DCMAKE_CUDA_COMPILER=/usr/local/cuda/bin/nvcc \
  -DCMAKE_CUDA_ARCHITECTURES=86 \
  -DCMAKE_BUILD_TYPE=Release

# 开始编译（使用 8 个并行任务，可根据 CPU 核心数调整）
cmake --build build --parallel 8 --verbose

参数解释：

-DGGML_CUDA=ON：启用 CUDA 加速。
-DCMAKE_CUDA_ARCHITECTURES=86：为计算能力 8.6 的 GPU 编译（例如 RTX 3090/3080）。请根据你的 GPU 修改此值，否则运行时会报错或不生效。
-DCMAKE_BUILD_TYPE=Release：构建发布版本，启用优化（原文未加，但推荐加上）。
-DGGML_CPU_ALL_VARIANTS=OFF：仅为本机 CPU 优化，避免编译所有指令集变体，大幅减少编译时间。

编译完成后，可执行文件位于 build/ollama。你可以将其复制到 /usr/local/bin 以便全局使用：

sudo cp build/ollama /usr/local/bin/ollama

第 6 步：启动 Ollama 服务

启动服务前，先设置运行时环境变量：

export OLLAMA_HOST="0.0.0.0:8080"          # 监听所有网卡的 8080 端口（若仅本机使用可改为 127.0.0.1:8080）
export OLLAMA_FLASH_ATTENTION="1"           # 启用 Flash Attention，加速长上下文推理
export OLLAMA_KV_CACHE_TYPE="q8_0"          # KV 缓存使用 8-bit 量化，节省显存
export OLLAMA_NUM_PARALLEL="2"              # 同时处理 2 个请求（单用户可设为 1 以省显存）
export OLLAMA_MAX_LOADED_MODELS="1"         # 最多同时加载 1 个模型
export OLLAMA_KEEP_ALIVE="10m"              # 模型空闲 10 分钟后自动卸载
export OLLAMA_CONTEXT_LENGTH="49152"        # 默认上下文长度（需与模型参数匹配）

然后启动服务：

# 如果已复制到 PATH，可直接运行：
ollama serve

# 否则在源码目录使用：
./build/ollama serve

启动后，可通过另一个终端测试服务是否正常：

curl http://localhost:8080/api/tags

如果返回 {"models":[]}（尚未下载模型）则说明服务已运行。

第 7 步：拉取并创建自定义模型

拉取基础模型

# 将 qwen3.8:27b 替换为你实际需要的模型
ollama pull qwen3.8:27b

创建自定义模型（固定上下文长度）

为了让模型在 API 调用中自动使用 49152 上下文，我们基于基础模型创建一个新模型：

cat > Modelfile << 'EOF'
FROM qwen3.8:27b
PARAMETER num_ctx 49152
EOF

ollama create qwen3.8-cc:27b -f Modelfile

说明：FROM 指定基础模型，PARAMETER num_ctx 设置默认上下文窗口大小。之后通过 qwen3.8-cc:27b 调用时无需再传 num_ctx 参数。

创建完成后，验证模型已存在：

ollama list

第 8 步：配置 Claude Code

Claude Code 是 Anthropic 的命令行 AI 编程助手，默认连接 Anthropic 云服务。我们通过修改其全局配置文件 ~/.claude.json，将所有模型端点指向本地 Ollama。

安装 Node.js 和 Claude Code

Claude Code 需要 Node.js 环境。使用 nvm 安装 Node.js 24：

sudo apt install curl -y
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc

nvm install 24
npm install -g @anthropic-ai/claude-code

配置环境变量并写入配置文件

# 定义变量（仅用于生成配置文件）
export AI_MODEL=qwen3.8-cc:27b
export AI_AUTH_TOKEN="ollama"
export AI_BASE_URL=http://192.168.1.100:8080   # 请替换为你的 Ollama 服务地址

# 备份已有配置（如果存在）
[ -f ~/.claude.json ] && cp ~/.claude.json ~/.claude.json.bak

# 写入新的配置
cat > ~/.claude.json << EOF
{
  "firstStartTime": "2026-04-17T07:13:49.158Z",
  "opusProMigrationComplete": true,
  "sonnet1m45MigrationComplete": true,
  "migrationVersion": 11,
  "changelogLastFetched": 1776410045295,
  "hasCompletedOnboarding": true,
  "env": {
    "IS_SANDBOX": "1",
    "ANTHROPIC_AUTH_TOKEN": "$AI_AUTH_TOKEN",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "ANTHROPIC_BASE_URL": "$AI_BASE_URL",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "$AI_MODEL",
    "ANTHROPIC_REASONING_MODEL": "$AI_MODEL",
    "ANTHROPIC_MODEL": "$AI_MODEL",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "$AI_MODEL",
    "ANTHROPIC_API_KEY": "",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "$AI_MODEL",
    "ANTHROPIC_SMALL_FAST_MODEL": "$AI_MODEL",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "49152"
  }
}
EOF

关键点解释：

env 对象中的变量会在 Claude Code 启动时加载为环境变量。
ANTHROPIC_BASE_URL 指向本地 Ollama 服务。如果 Claude Code 无法连接，尝试在地址末尾添加 /v1，例如 http://192.168.1.100:8080/v1。
ANTHROPIC_AUTH_TOKEN 设置为任意字符串即可，因为本地服务不校验。
所有 ANTHROPIC_*_MODEL 都指向同一个本地模型，确保 Claude Code 的各个功能（快模型、慢模型、推理模型）都使用本地服务。
CLAUDE_CODE_MAX_CONTEXT_TOKENS 与模型上下文保持一致。

第 9 步：运行 Claude Code

claude --dangerously-skip-permissions

安全警告：--dangerously-skip-permissions 会跳过 Claude Code 的文件操作权限确认，可能带来安全风险。仅在可信的代码库和隔离环境中使用，切勿在包含敏感数据的项目上随意开启。

运行后，Claude Code 会使用本地 Ollama 模型进行对话和代码编辑。你可以通过日志确认请求是否发送到了本地服务。

性能参考

以下是在某次推理中 Ollama 服务打印的生成速度统计：

slot print_timing: id  0 | task 3184 | n_gen =   3469, tg =  47.43 t/s, tg_3s =  57.78 t/s
slot print_timing: id  0 | task 3184 | n_gen =   3605, tg =  47.34 t/s, tg_3s =  45.04 t/s
slot print_timing: id  0 | task 3184 | n_gen =   3761, tg =  47.51 t/s, tg_3s =  51.73 t/s
...
slot print_timing: id  0 | task 3184 | n_gen =   5027, tg =  48.59 t/s, tg_3s =  64.29 t/s

其中 tg 表示每秒生成的 token 数（tokens/s），tg_3s 是最近 3 秒的平均速度。约 47–48 t/s 的速度对于较大模型来说已经相当流畅，接近真人阅读速度。

如果你的硬件不同，实际速度可能有差异。可以通过调整量化方式、上下文长度或启用 Flash Attention 来优化。

第 10 步：配置 Codex CLI（可选）

Codex CLI 是 OpenAI 推出的命令行编程代理，同样可以指向本地 Ollama 服务。

安装 Codex

npm install -g @openai/codex

创建配置文件

mkdir -p ~/.codex/

# 注意：以下路径中的 ~ 建议替换为 /home/$USER 或 $HOME，避免 TOML 解析问题
cat > ~/.codex/config.toml << 'EOF'
model_provider = "ollama-launch"
model = "qwen3.8-cc:27b"
model_catalog_json = "/home/$USER/.codex/model-catalog.local.json"

[model_providers.ollama-launch]
name = "Ollama"
base_url = "http://192.168.1.100:8080/v1/"
wire_api = "responses"
requires_openai_auth = false
supports_websockets = false
EOF

参数解释：

base_url：必须指向 Ollama 的 OpenAI 兼容端点，末尾带 /v1/。
wire_api = "responses"：Codex 使用 OpenAI Responses API。如果 Ollama 不支持该接口，请将其改为 "chat_completions"。
requires_openai_auth = false：本地服务无需 API Key。
model_catalog_json：指向模型目录文件，需要手动创建。

创建模型目录文件

cat > ~/.codex/model-catalog.local.json << 'EOF'
{
  "models": [
    {
      "slug": "qwen3.8-cc:27b",
      "display_name": "qwen3.8-cc:27b",
      "description": null,
      "supported_reasoning_levels": [],
      "default_reasoning_level": "medium",
      "shell_type": "shell_command",
      "visibility": "list",
      "supported_in_api": true,
      "priority": 1,
      "availability_nux": null,
      "upgrade": null,
      "base_instructions": "You are a helpful coding agent.",
      "supports_reasoning_summaries": false,
      "support_verbosity": false,
      "default_verbosity": null,
      "apply_patch_tool_type": null,
      "truncation_policy": { "mode": "bytes", "limit": 10000 },
      "supports_parallel_tool_calls": false,
      "experimental_supported_tools": [],
      "effective_context_window_percent": 95,
      "context_window": 49152
    }
  ]
}
EOF

关键字段：

slug：模型标识，必须与 config.toml 中的 model 一致。
context_window：模型最大上下文窗口，与 Ollama 设置一致。
effective_context_window_percent：实际使用的上下文比例，留出一定余量避免溢出。

第 11 步：运行 Codex

codex --sandbox danger-full-access --ask-for-approval never

安全警告：danger-full-access 和 --ask-for-approval never 赋予 Codex 完全的文件系统访问权限且不进行任何确认，风险极高。请仅在完全可信且隔离的环境中使用，例如专用虚拟机或容器。

四、常见问题与排查

1. 编译时提示找不到 nvcc

确认 CUDA Toolkit 已安装：nvcc --version。
检查 /usr/local/cuda/bin/nvcc 是否存在，若路径不同，修改 CUDACXX 和 -DCMAKE_CUDA_COMPILER 的值。

2. 编译时提示 CUDA 架构不支持

查询你的 GPU 计算能力，修改 -DCMAKE_CUDA_ARCHITECTURES。
例如 RTX 4090 是 8.9，应设为 89；A100 是 8.0，应设为 80。

3. 模型加载时显存不足（OOM）

降低上下文长度，例如将 OLLAMA_CONTEXT_LENGTH 改为 16384 或 8192。
使用更小的量化模型，例如 qwen3:8b 或 qwen3:14b。
将 OLLAMA_KV_CACHE_TYPE 改为 q4_0 进一步节省显存。
减少 OLLAMA_NUM_PARALLEL 至 1。

4. Claude Code 无法连接本地模型

检查 ANTHROPIC_BASE_URL 是否正确，尝试添加 /v1 后缀。
确认 Ollama 服务正在运行且端口监听正确：curl http://192.168.1.100:8080/api/tags。
确保模型名称与 Ollama 中 ollama list 显示的名称完全一致。
查看 ~/.claude.json 是否为合法 JSON（使用 jq . ~/.claude.json 验证）。

5. Codex 报错或连接失败

确认 base_url 以 /v1/ 结尾。
尝试将 wire_api 改为 "chat_completions"，因为并非所有 Ollama 版本都支持 Responses API。
检查模型目录文件中的 slug 是否与 config.toml 中 model 一致。
若使用 ~ 路径导致找不到模型目录，请替换为绝对路径。

6. 如何让环境变量永久生效？

将 export OLLAMA_MODELS、OLLAMA_HOST、OLLAMA_FLASH_ATTENTION 等写入 ~/.bashrc，然后执行 source ~/.bashrc。

五、安全提示

不要将 Ollama 服务直接暴露到公网：OLLAMA_HOST="0.0.0.0:8080" 会监听所有网卡，请务必通过防火墙限制访问来源，仅允许可信内网 IP。
谨慎使用跳过权限的参数：--dangerously-skip-permissions 和 --sandbox danger-full-access 会让 AI 拥有极大的文件操作权限，请勿在包含重要数据或生产环境的目录下使用。
定期备份配置文件：修改 ~/.claude.json、~/.codex/config.toml 前建议备份，以免配置丢失。