开源大模型本地部署与使用完全教程

从零开始，手把手教你在家用电脑上运行大语言模型

---

前言

大语言模型（LLM）已经深刻改变了我们与技术交互的方式。ChatGPT、Claude 等商业 API 虽然强大，但将数据发送到第三方服务器、按量付费、受限于网络连接——这些问题让越来越多的开发者和爱好者开始关注本地部署。

好消息是：开源大模型生态已经成熟到完全可以在个人电脑上运行高质量的 LLM。你不需要集群，不需要数百万美元的预算，一张消费级显卡甚至纯 CPU 就能开始。

本教程面向零基础开发者和 AI 爱好者，从为什么要做本地部署讲起，逐步覆盖模型选型、硬件规划、多种部署工具的使用、量化技术、微调、RAG 知识库，最终带你完成一个实战项目——搭建本地 AI 编程助手。

你将学到什么：

• 理解本地部署的优势和适用场景
• 选择适合自己的开源模型
• 使用 Ollama、llama.cpp、vLLM 等工具部署模型
• 使用 Open WebUI 获得类 ChatGPT 的图形界面
• 掌握模型量化技术，在有限硬件上运行更大模型
• 使用 LoRA 微调模型适应自己的需求
• 搭建本地 RAG 知识库系统
• 优化推理性能，榨干硬件潜力
• 完成一个完整的实战项目

---

目录

1. 为什么本地部署
2. 主流开源大模型概览
3. 硬件需求与规划
4. Ollama 本地部署
5. llama.cpp 部署
6. vLLM 高性能推理
7. Open WebUI 图形界面
8. 模型量化技术
9. LoRA 微调实战
10. RAG 本地知识库
11. 性能优化
12. 实战项目：搭建本地 AI 编程助手

---

1. 为什么本地部署

在讨论如何部署之前，我们先搞清楚一个问题：为什么要本地部署？ 调用 API 不是更简单吗？

答案取决于你的需求。本地部署并非在所有场景下都优于 API 调用，但它在某些关键领域具有不可替代的优势。

1.1 隐私保护

这是本地部署最核心的优势。当你通过 API 发送请求时，你的数据——可能是商业机密、私人对话、敏感文档——都会经过第三方服务器。即使服务商承诺"不使用你的数据训练模型"，数据仍然离开了你的控制范围。

本地部署意味着：

• 数据不出本机：所有推理都在你的硬件上完成，无需网络传输
• 无日志风险：不存在第三方服务器记录你的对话内容
• 合规优势：对于医疗、法律、金融等行业，数据合规是硬性要求，本地部署天然满足数据不出域的要求
• 完全自主：你对自己的数据有绝对控制权

真实场景举例：

• 医生用 AI 辅助分析病历，病历数据绝不能泄露
• 律师用 AI 整理案件材料，涉及客户隐私
• 企业用 AI 处理内部文档，包含商业秘密
• 个人日记、私人对话，不想被任何人看到

1.2 成本控制

API 调用按 token 计费，长期使用成本可能很高。假设你每天使用 GPT-4 级别的模型，输入约 50,000 tokens、输出约 10,000 tokens，按 GPT-4o 价格（输入 $2.5/百万 tokens，输出 $10/百万 tokens）计算，每月成本约 $6.75，每年约 $81。

看起来不多，但如果是团队 10 人使用或大量文档处理，每年成本可达数百甚至数千美元。而本地部署：一张 RTX 4060 Ti 16GB 约 ¥3,500，电费每月约 ¥15-30，模型本身免费——重度使用约 3-6 个月即可回本。

1.3 离线使用与自定义需求

本地部署不依赖网络连接，飞机上、高铁上、网络不稳定地区都能使用。同时，本地部署给你最大的自由度：选择任何开源模型、微调定制、修改模型行为、集成到任意系统、批量处理无限制。

1.4 与 API 调用的对比

维度	本地部署	API 调用
隐私	数据完全在本地	数据经过第三方服务器
成本	一次性硬件投入	按量持续付费
网络	不需要网络	依赖稳定网络
延迟	取决于硬件，无网络延迟	受网络影响
模型质量	取决于选择的开源模型	通常是最强商业模型
上手难度	需要一定技术基础	几行代码即可调用
定制化	完全自由	有限
批量处理	无限制	受速率限制

实际使用中，混合方案往往是最优解：敏感数据处理用本地模型，一般性任务用 API 调用。

---

2. 主流开源大模型概览

2.1 Meta Llama 系列

Llama 是 Meta 推出的开源大模型系列，是开源大模型领域的标杆。

Llama 3（2024年4月）：包含 8B 和 70B 版本，训练数据量达 15 万亿 tokens，128K 上下文窗口，支持工具调用。

Llama 3.1（2024年7月）：405B 版本首次让开源模型达到 4000 亿参数级别，128K 上下文，多语言增强。

Llama 3.2（2024年9月）：引入轻量版（1B/3B）和视觉版（11B/90B Vision），支持移动端和多模态。

Llama 4（2025年）：采用 MoE 架构，Scout（17B 活跃/109B 总）和 Maverick（17B 活跃/400B 总），支持数百万 token 上下文。

2.2 阿里 Qwen（通义千问）系列

Qwen 2.5：多种尺寸（0.5B-72B），中文能力一流，Qwen2.5-Coder 代码能力出色，支持 128K 上下文。

Qwen 3（2025年）：支持"深度思考"模式，MoE 模型 Qwen3-235B-A22B，支持 100+ 种语言，Agent 能力优秀。

# Qwen 3 通过 Ollama 部署
ollama pull qwen3:8b
ollama run qwen3:8b "请详细分析快速排序算法的时间复杂度"

2.3 DeepSeek 系列

DeepSeek V3：MoE 架构（671B 总参/37B 活跃），多项基准达 GPT-4 级别，训练成本仅约 557 万美元。

DeepSeek R1：推理专用模型，擅长数学、代码、逻辑推理，提供 1.5B-70B 蒸馏版本。

ollama pull deepseek-r1:8b
ollama run deepseek-r1:8b "证明根号2是无理数"

2.4 其他重要模型

Mistral 系列：法国 Mistral AI 推出，Mixtral 采用 MoE 架构，多语言支持优秀。

Gemma 系列：Google 推出的轻量级模型，Gemma 2 的 27B 版本性价比极高。

Yi 系列：零一万物推出，中英双语能力均衡，200K 上下文窗口。

Phi 系列：Microsoft 推出，小模型大能力，3.8B 参数性能惊人。

2.5 模型选型建议

• 通用对话（中文）：Qwen 2.5/3（7B 或 14B）
• 通用对话（英文）：Llama 3.1 8B 或 Gemma 2 9B
• 代码开发：Qwen2.5-Coder 7B/32B
• 数学推理：DeepSeek R1 蒸馏版
• 资源受限：Phi-3.5 Mini（3.8B）、Qwen 2.5 3B
• 追求性能：Qwen 2.5 72B（量化版）、DeepSeek V3（量化版）

---

3. 硬件需求与规划

3.1 显存是关键

大模型推理的核心瓶颈是显存（VRAM）。基本公式：显存需求（GB）≈ 参数量（B）× 每参数字节数。

不同精度下的显存需求：

模型	FP16 显存	INT8 显存	INT4 显存
7B	14 GB	7 GB	3.5 GB
13B	26 GB	13 GB	6.5 GB
34B	68 GB	34 GB	17 GB
70B	140 GB	70 GB	35 GB

实际显存需求还要加上 KV Cache、激活值等开销，通常比纯模型参数多 20-50%。

3.2 GPU 选型

消费级推荐：

• RTX 4060 Ti 16GB（¥3,500）：7B FP16 / 13B INT4
• RTX 4090 24GB（¥14,000）：13B FP16 / 34B INT4
• RTX 5090 32GB（¥18,000）：34B INT8 / 70B INT4

Apple Silicon：

• M2 Pro 16GB：流畅运行 7B 模型
• M2 Max 32GB：运行 13B 模型
• M3 Max 128GB：运行 70B 模型

Mac 的 M 系列芯片使用统一内存架构，GPU 可以直接访问全部内存，这是 Mac 运行大模型的独特优势。

3.3 CPU 推理

没有 GPU 也能运行大模型。关键因素是核心数、内存带宽和 AVX-512 支持。以 llama.cpp Q4_K_M 量化为例：i7-13700K 运行 7B 模型约 12 tokens/s，M3 Max 约 40 tokens/s。

3.4 内存与存储

• 系统内存最低 16GB，推荐 32GB
• 存储至少预留 100GB，使用 SSD
• 7B 模型 Q4_K_M 量化约 4GB，70B 约 40GB

3.5 云 GPU 方案

本地硬件不够时，云 GPU 是好选择。国内推荐 AutoDL（RTX 4090 约 ¥2.5/小时），海外推荐 Vast.ai（约 $0.3/小时）。

---

4. Ollama 本地部署

Ollama 是目前最简单、最流行的本地大模型部署工具，把复杂的模型下载、配置、推理过程封装成简单的命令行操作。

4.1 安装 Ollama

# Linux 一键安装
curl -fsSL https://ollama.com/install.sh | sh

# macOS（Homebrew）
brew install ollama

# Windows：访问 https://ollama.com/download 下载安装程序

# 验证安装
ollama --version

4.2 模型下载与管理

# 下载模型
ollama pull qwen2.5:7b          # 通用对话（中文优秀）
ollama pull llama3.1:8b          # 通用对话（英文优秀）
ollama pull deepseek-r1:8b       # 推理任务
ollama pull codellama:7b         # 代码生成
ollama pull qwen3:8b             # 思考模式
ollama pull phi3.5:3.8b          # 轻量模型

# 查看已下载模型
ollama list

# 运行模型（交互式对话）
ollama run qwen2.5:7b

# 单次问答
ollama run qwen2.5:7b "什么是机器学习？"

# 使用系统提示词
ollama run qwen2.5:7b --system "你是Python编程助手，只回答Python相关问题。"

# 删除模型
ollama rm qwen2.5:7b

# 查看模型信息
ollama show qwen2.5:7b

4.3 自定义 Modelfile

Modelfile 是 Ollama 的模型配置文件，类似于 Dockerfile。

# Modelfile - 自定义代码助手
FROM qwen2.5-coder:7b

SYSTEM """
你是一个专业的全栈编程助手。
规则：
1. 代码必须包含详细注释
2. 优先使用最佳实践
3. 考虑边界情况和错误处理
4. 使用中文解释，代码注释用英文
"""

PARAMETER temperature 0.3
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER num_predict 4096
PARAMETER repeat_penalty 1.1

# 创建自定义模型
ollama create code-assistant -f Modelfile

# 使用自定义模型
ollama run code-assistant "用Python写一个快速排序"

4.4 API 调用

Ollama 提供 OpenAI 兼容的 API 接口，默认监听 http://localhost:11434。

# 基本 API 调用
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "为什么天空是蓝色的？",
  "stream": false
}'

# 流式输出
curl http://localhost:11434/api/generate -d '{
  "model": "qwen2.5:7b",
  "prompt": "写一首关于春天的诗",
  "stream": true
}'

# 对话模式（多轮）
curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [
    {"role": "system", "content": "你是一个友好的助手"},
    {"role": "user", "content": "你好！"}
  ],
  "stream": false
}'

Python 调用示例：

import requests
import json

# 基本调用
def chat(prompt, model="qwen2.5:7b"):
    response = requests.post(
        "http://localhost:11434/api/generate",
        json={
            "model": model,
            "prompt": prompt,
            "stream": False,
            "options": {
                "temperature": 0.7,
                "num_predict": 2048
            }
        }
    )
    return response.json()["response"]

# 流式调用
def chat_stream(prompt, model="qwen2.5:7b"):
    response = requests.post(
        "http://localhost:11434/api/generate",
        json={"model": model, "prompt": prompt, "stream": True},
        stream=True
    )
    for line in response.iter_lines():
        if line:
            data = json.loads(line)
            print(data["response"], end="", flush=True)
            if data["done"]:
                break

# OpenAI 兼容接口
from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"  # 随意填写，Ollama 不验证
)

response = client.chat.completions.create(
    model="qwen2.5:7b",
    messages=[
        {"role": "system", "content": "你是一个友好的助手"},
        {"role": "user", "content": "你好！"}
    ]
)
print(response.choices[0].message.content)

4.5 多模型切换

# 同时下载多个模型
ollama pull qwen2.5:7b
ollama pull llama3.1:8b
ollama pull deepseek-r1:8b
ollama pull codellama:7b

# 根据任务切换模型
# 日常对话
ollama run qwen2.5:7b

# 代码任务
ollama run codellama:7b

# 推理任务
ollama run deepseek-r1:8b

# 查看运行中的模型
ollama ps

4.6 Ollama 环境变量配置

# 设置模型存储路径
export OLLAMA_MODELS=/path/to/models

# 设置监听地址（允许远程访问）
export OLLAMA_HOST=0.0.0.0:11434

# 设置并发数
export OLLAMA_NUM_PARALLEL=4

# 设置最大加载模型数
export OLLAMA_MAX_LOADED_MODELS=2

# GPU 层 offload 设置
export OLLAMA_NUM_GPU=999  # 尽可能多使用 GPU

---

5. llama.cpp 部署

llama.cpp 是一个纯 C/C++ 实现的 LLM 推理引擎，是许多工具（包括 Ollama）的底层基础。它对硬件要求最低，支持 CPU 推理，是资源受限环境的首选。

5.1 编译安装

# 克隆仓库
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# Linux 编译（支持 CUDA）
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release -j$(nproc)

# Linux 编译（仅 CPU）
cmake -B build
cmake --build build --config Release -j$(nproc)

# macOS 编译（支持 Metal）
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release

# 验证编译
./build/bin/llama-cli --help

5.2 GGUF 模型格式

llama.cpp 使用 GGUF（GPT-Generated Unified Format）格式，这是专门为 CPU/GPU 混合推理设计的模型格式。

# 下载 GGUF 模型（Hugging Face）
# 推荐来源：
# - https://huggingface.co/TheBloke（大量量化模型）
# - https://huggingface.co/Qwen（官方量化版本）
# - https://huggingface.co/bartowski（社区量化）

# 使用 huggingface-cli 下载
pip install huggingface-hub
huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF qwen2.5-7b-instruct-q4_k_m.gguf --local-dir ./models

# 转换 Hugging Face 模型为 GGUF
python convert_hf_to_gguf.py /path/to/huggingface/model --outfile model.gguf --outtype q8_0

5.3 运行模型

# 基本运行（交互模式）
./build/bin/llama-cli -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -c 4096 \
  --temp 0.7 \
  -ngl 999 \
  -i

# 参数说明：
# -m: 模型文件路径
# -c: 上下文长度
# --temp: 温度参数
# -ngl: GPU offload 层数（999表示全部offload到GPU）
# -i: 交互模式

# 单次推理
./build/bin/llama-cli -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
  -p "请解释什么是递归：" \
  -n 512 \
  --temp 0.7

# 启动 API Server
./build/bin/llama-server \
  -m ./models/qwen2.5-7b-instruct-q4_k_m.gguf \
  --host 0.0.0.0 \
  --port 8080 \
  -c 4096 \
  -ngl 999

# API 调用
curl http://localhost:8080/v1/chat/completions -d '{
  "model": "qwen2.5-7b",
  "messages": [{"role": "user", "content": "你好"}],
  "temperature": 0.7
}'

5.4 性能优化参数

# 优化推理速度
./build/bin/llama-cli -m ./models/model.gguf \
  -c 4096 \
  -ngl 999 \           # 全部层 offload 到 GPU
  -t 8 \               # CPU 线程数（CPU推理时重要）
  --mlock \            # 锁定内存，避免换页
  --no-mmap \          # 禁用内存映射（大模型推荐）
  -b 512 \             # 批处理大小
  -ub 512 \            # 提示批处理大小
  -i

# 监控性能
# 运行时会显示：
# prompt eval time: xxx ms / yyy tokens (zzz ms per token)
# eval time: xxx ms / yyy tokens (zzz ms per token)
# 这里的 ms per token 就是推理速度

5.5 量化操作

llama.cpp 自带量化工具：

# 将 FP16 模型量化为 Q4_K_M
./build/bin/llama-quantize \
  ./models/model-f16.gguf \
  ./models/model-q4_k_m.gguf \
  Q4_K_M

# 常用量化类型：
# Q4_0: 4-bit 量化，体积最小，质量较低
# Q4_K_M: 4-bit K-quant，推荐，平衡体积和质量
# Q5_K_M: 5-bit K-quant，质量更好，体积稍大
# Q6_K: 6-bit K-quant，高质量
# Q8_0: 8-bit 量化，接近原始质量

---

6. vLLM 高性能推理

vLLM 是一个高吞吐量、低延迟的 LLM 推理和服务引擎，专为生产环境设计。如果你需要同时服务多个用户或处理大量请求，vLLM 是最佳选择。

6.1 安装 vLLM

# 安装 vLLM（需要 CUDA 12.x）
pip install vllm

# 或者从源码安装
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

6.2 PagedAttention 原理

vLLM 的核心创新是 PagedAttention。传统推理引擎在处理 KV Cache 时需要连续的内存空间，导致大量内存浪费（内部碎片和外部碎片）。PagedAttention 借鉴了操作系统的虚拟内存和分页技术：

• 分页管理：将 KV Cache 分成固定大小的块（page），不需要连续存储
• 按需分配：只在需要时分配内存块，避免预分配浪费
• 动态增长：序列长度增加时动态分配新块
• 内存共享：多个请求可以共享相同的 KV Cache 块

结果：内存利用率提升 2-4 倍，吞吐量提升 2-4 倍。

6.3 启动 API Server

# 基本启动
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --host 0.0.0.0 \
  --port 8000

# 带量化
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --quantization awq \
  --host 0.0.0.0 \
  --port 8000

# 指定 GPU 内存利用率
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.9 \
  --max-model-len 8192 \
  --host 0.0.0.0 \
  --port 8000

# 多 GPU 张量并行
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 2 \
  --host 0.0.0.0 \
  --port 8000

6.4 API 调用

# 基本对话
curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "messages": [
    {"role": "system", "content": "你是一个友好的助手"},
    {"role": "user", "content": "你好！"}
  ],
  "temperature": 0.7,
  "max_tokens": 2048
}'

# 流式输出
curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
  "model": "Qwen/Qwen2.5-7B-Instruct",
  "messages": [{"role": "user", "content": "写一首诗"}],
  "stream": true
}'

# 批量推理（Python）
from openai import OpenAI

client = OpenAI(base_url="http://localhost:8000/v1", api_key="token-abc123")

# 批量发送多个请求
prompts = [
    "解释什么是机器学习",
    "Python 和 Java 的区别",
    "如何优化 SQL 查询"
]

for prompt in prompts:
    response = client.chat.completions.create(
        model="Qwen/Qwen2.5-7B-Instruct",
        messages=[{"role": "user", "content": prompt}],
        max_tokens=512
    )
    print(f"Q: {prompt}")
    print(f"A: {response.choices[0].message.content}\n")

6.5 吞吐量优化

# 关键优化参数

# 1. 调整 GPU 内存利用率（默认 0.9）
--gpu-memory-utilization 0.95

# 2. 设置最大并发请求数
--max-num-seqs 256

# 3. 调整最大模型长度
--max-model-len 4096

# 4. 启用前缀缓存（相同前缀的请求共享 KV Cache）
--enable-prefix-caching

# 5. 使用量化减少显存占用
--quantization awq    # 或 gptq

# 6. 调整批处理大小
--max-num-batched-tokens 8192

---

7. Open WebUI 图形界面

Open WebUI（前身为 Ollama WebUI）是一个功能丰富的自托管 Web 界面，提供类似 ChatGPT 的用户体验。

7.1 Docker 部署

# 使用 Docker 部署（推荐）
docker run -d -p 3000:8080 \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main

# 使用 Docker Compose
# 创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://host.docker.internal:11434
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:
EOF

# 启动
docker compose up -d

部署完成后，访问 http://localhost:3000 即可使用。首次访问需要创建管理员账号。

7.2 模型配置

在 Open WebUI 中：

1. 进入 Settings（设置）
2. 选择 Models（模型）
3. 可以看到所有通过 Ollama 下载的模型
4. 可以为每个模型设置默认参数（温度、上下文长度等）

7.3 知识库上传

Open WebUI 支持 RAG（检索增强生成）功能：

1. 进入 Workspace → Knowledge
2. 点击 Create Knowledge Base
3. 上传文档（支持 PDF、TXT、Markdown 等格式）
4. 在对话中使用 #知识库名称 引用知识库

# 如果需要更好的文档处理，可以配置外部向量数据库
# 在 docker-compose.yml 中添加 ChromaDB
services:
  chromadb:
    image: chromadb/chroma:latest
    ports:
      - "8001:8000"
    volumes:
      - chromadb:/chroma/chroma

7.4 多用户管理

Open WebUI 支持多用户：

• 管理员可以在 Admin Panel 中管理用户
• 支持用户注册（可关闭）
• 支持角色权限管理（管理员、普通用户）
• 每个用户有独立的对话历史

7.5 自定义设置

# 环境变量配置
environment:
  # 默认模型
  - DEFAULT_MODELS=qwen2.5:7b
  # 允许注册
  - ENABLE_SIGNUP=true
  # API 密钥（用于外部访问）
  - API_KEY=your-secret-key
  # 响应超时
  - STREAM_REQUEST_TIMEOUT=120

---

8. 模型量化技术

量化是将模型参数从高精度（FP16/FP32）转换为低精度（INT8/INT4）的技术，可以显著减小模型体积和显存占用，同时保持大部分性能。

8.1 量化原理

基本概念：

• FP16：16位浮点，2字节/参数，精度最高
• INT8：8位整数，1字节/参数，精度良好
• INT4：4位整数，0.5字节/参数，精度可接受

量化的核心思想是用更少的比特数表示模型参数。以 INT8 量化为例：

原始 FP16 值: [0.1234, -0.5678, 0.9012, ...]
INT8 量化: 找到最大值和最小值，线性映射到 [-128, 127]
反量化: 乘以缩放因子恢复近似值

8.2 GGUF 量化（llama.cpp）

GGUF 是 llama.cpp 使用的量化格式，支持多种量化级别：

量化类型	比特数	大小(7B)	质量	适用场景
Q2_K	2-bit	~2.5 GB	较低	极端资源受限
Q3_K_M	3-bit	~3.0 GB	一般	资源受限
Q4_0	4-bit	~3.8 GB	一般	基本使用
Q4_K_M	4-bit	~4.0 GB	良好	推荐默认
Q5_K_M	5-bit	~4.8 GB	很好	追求质量
Q6_K	6-bit	~5.5 GB	优秀	高质量需求
Q8_0	8-bit	~7.0 GB	接近原始	最高质量

# 使用 llama.cpp 量化
./build/bin/llama-quantize \
  ./models/model-f16.gguf \
  ./models/model-q4_k_m.gguf \
  Q4_K_M

# 量化类型选择建议：
# - 日常对话：Q4_K_M（平衡）
# - 代码生成：Q5_K_M（代码对精度更敏感）
# - 数学推理：Q6_K 或 Q8_0（数学需要高精度）
# - 极端资源受限：Q3_K_M 或 Q2_K（质量损失明显）

8.3 GPTQ 量化

GPTQ 是一种基于二阶信息的训练后量化方法，精度损失较小。

# 安装 auto-gptq
pip install auto-gptq

# GPTQ 量化示例
from transformers import AutoTokenizer
from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig

model_id = "Qwen/Qwen2.5-7B-Instruct"
quantize_config = BaseQuantizeConfig(
    bits=4,           # 量化位数
    group_size=128,   # 量化组大小
    damp_percent=0.01,
    desc_act=True,    # 按激活值降序量化
)

# 加载模型
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoGPTQForCausalLM.from_pretrained(model_id, quantize_config)

# 准备校准数据
calibration_data = [
    tokenizer("这是一段校准文本", return_tensors="pt"),
    # ... 更多校准样本
]

# 执行量化
model.quantize(calibration_data)

# 保存量化模型
model.save_quantized("./qwen2.5-7b-gptq-4bit")
tokenizer.save_pretrained("./qwen2.5-7b-gptq-4bit")

8.4 AWQ 量化

AWQ（Activation-aware Weight Quantization）是一种更先进的量化方法，通过分析激活值来保护重要权重。

# 安装 autoawq
pip install autoawq

# AWQ 量化示例
from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_path = "Qwen/Qwen2.5-7B-Instruct"
quant_path = "./qwen2.5-7b-awq-4bit"

# 加载模型
model = AutoAWQForCausalLM.from_pretrained(model_path)
tokenizer = AutoTokenizer.from_pretrained(model_path)

# 量化配置
quant_config = {
    "zero_point": True,
    "q_group_size": 128,
    "w_bit": 4,
    "version": "GEMM"
}

# 执行量化
model.quantize(tokenizer, quant_config=quant_config)

# 保存
model.save_quantized(quant_path)
tokenizer.save_pretrained(quant_path)

8.5 量化对精度的影响

量化不可避免地会带来精度损失，但程度因任务而异：

任务类型	Q4_K_M 精度损失	Q8_0 精度损失
通用对话	几乎无损	无损
代码生成	1-3%	<1%
数学推理	3-5%	1-2%
知识问答	2-4%	<1%
创意写作	几乎无损	无损

建议： 对于大多数使用场景，Q4_K_M 是最佳平衡点。如果对精度要求极高（如数学推理），可以使用 Q6_K 或 Q8_0。

---

9. LoRA 微调实战

LoRA（Low-Rank Adaptation）是一种高效的模型微调方法，它不需要修改原始模型的所有参数，而是在模型的关键层旁边添加小型可训练矩阵，大大降低了微调的计算和存储成本。

9.1 LoRA 原理

传统微调需要更新模型的所有参数（如 7B 模型有 70 亿参数），需要巨大显存。LoRA 的核心思想：

• 冻结原始模型参数不变
• 在注意力层的 Q、K、V、O 矩阵旁边添加低秩分解矩阵
• 只训练这些小型矩阵（通常只有原参数的 0.1-1%）
• 推理时将 LoRA 权重合并回原模型，不增加推理开销

LoRA 超参数：

• r（秩）：低秩矩阵的维度，通常 8-64，越大拟合能力越强但参数越多
• lora_alpha：缩放因子，通常设为 r 的 2 倍
• target_modules：应用 LoRA 的模块，通常包括 q_proj、k_proj、v_proj、o_proj
• lora_dropout：Dropout 比率，防止过拟合

9.2 训练数据准备

训练数据通常使用 JSONL 格式，每行一个对话样本：

{"conversations": [{"role": "system", "content": "你是一个专业的Python编程助手"}, {"role": "user", "content": "如何在Python中读取CSV文件？"}, {"role": "assistant", "content": "在Python中读取CSV文件有多种方法：\n\n1. 使用 csv 模块：\n```python\nimport csv\nwith open('data.csv', 'r', encoding='utf-8') as f:\n    reader = csv.reader(f)\n    for row in reader:\n        print(row)\n```\n\n2. 使用 pandas（推荐）：\n```python\nimport pandas as pd\ndf = pd.read_csv('data.csv')\nprint(df.head())\n```"}]}
{"conversations": [{"role": "system", "content": "你是一个专业的Python编程助手"}, {"role": "user", "content": "什么是列表推导式？"}, {"role": "assistant", "content": "列表推导式（List Comprehension）是Python中创建列表的简洁语法。\n\n基本格式：`[表达式 for 变量 in 可迭代对象 if 条件]`\n\n示例：\n```python\n# 传统方式\nsquares = []\nfor x in range(10):\n    squares.append(x ** 2)\n\n# 列表推导式\nsquares = [x ** 2 for x in range(10)]\n\n# 带条件过滤\nevens = [x for x in range(20) if x % 2 == 0]\n```"}]}

数据准备建议：

• 样本数量：至少 100 条，推荐 500-1000 条
• 数据质量比数量更重要
• 确保数据格式一致
• 覆盖目标任务的各种场景
• 可以使用 GPT-4 等强模型生成训练数据

9.3 使用 Hugging Face PEFT 微调

# 安装依赖
pip install torch transformers datasets peft accelerate bitsandbytes trl

# lora_finetune.py - LoRA 微调脚本
import torch
from datasets import load_dataset
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    BitsAndBytesConfig,
    TrainingArguments,
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer

# 配置
model_name = "Qwen/Qwen2.5-7B-Instruct"
output_dir = "./qwen2.5-7b-lora"
dataset_path = "./data/train.jsonl"

# 4-bit 量化配置（减少显存占用）
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

# 加载模型和分词器
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
tokenizer.pad_token = tokenizer.eos_token

# 准备模型
model = prepare_model_for_kbit_training(model)

# LoRA 配置
lora_config = LoraConfig(
    r=16,                          # 秩
    lora_alpha=32,                 # 缩放因子
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj"
    ],
    lora_dropout=0.05,
    bias="none",
    task_type="CAUSAL_LM",
)

# 应用 LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出示例: trainable params: 13,631,488 || all params: 7,615,616,000 || trainable%: 0.179%

# 加载数据集
dataset = load_dataset("json", data_files=dataset_path, split="train")

# 训练参数
training_args = TrainingArguments(
    output_dir=output_dir,
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    weight_decay=0.01,
    warmup_ratio=0.03,
    lr_scheduler_type="cosine",
    logging_steps=10,
    save_steps=100,
    save_total_limit=3,
    fp16=True,
    optim="paged_adamw_8bit",
    report_to="none",
)

# 创建训练器
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    tokenizer=tokenizer,
    max_seq_length=2048,
)

# 开始训练
trainer.train()

# 保存 LoRA 权重
trainer.save_model(output_dir)
tokenizer.save_pretrained(output_dir)

print(f"训练完成！模型保存在: {output_dir}")

9.4 效果评估

# evaluate_lora.py - 评估微调效果
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
import torch

# 加载基础模型
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 加载 LoRA 权重
model = PeftModel.from_pretrained(base_model, "./qwen2.5-7b-lora")
tokenizer = AutoTokenizer.from_pretrained("./qwen2.5-7b-lora")

# 测试对话
def test_chat(prompt, system_prompt="你是一个专业的Python编程助手"):
    messages = [
        {"role": "system", "content": system_prompt},
        {"role": "user", "content": prompt}
    ]
    text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
    inputs = tokenizer(text, return_tensors="pt").to(model.device)
    
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_new_tokens=1024,
            temperature=0.7,
            do_sample=True,
        )
    
    response = tokenizer.decode(outputs[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True)
    return response

# 测试用例
test_prompts = [
    "如何用Python实现二分查找？",
    "解释Python中的装饰器是什么？",
    "如何处理Python中的异常？",
]

for prompt in test_prompts:
    print(f"Q: {prompt}")
    print(f"A: {test_chat(prompt)}")
    print("-" * 50)

9.5 模型合并

将 LoRA 权重合并回基础模型，得到独立的完整模型：

# merge_lora.py - 合并 LoRA 权重
from transformers import AutoModelForCausalLM, AutoTokenizer
from peft import PeftModel
import torch

# 加载基础模型
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

# 加载 LoRA
model = PeftModel.from_pretrained(base_model, "./qwen2.5-7b-lora")

# 合并权重
merged_model = model.merge_and_unload()

# 保存合并后的模型
merged_model.save_pretrained("./qwen2.5-7b-merged")
tokenizer = AutoTokenizer.from_pretrained("./qwen2.5-7b-lora")
tokenizer.save_pretrained("./qwen2.5-7b-merged")

print("模型合并完成！")

# 转换为 GGUF 格式（用于 llama.cpp/Ollama）
# python convert_hf_to_gguf.py ./qwen2.5-7b-merged --outfile qwen2.5-7b-merged.gguf --outtype q4_k_m

---

10. RAG 本地知识库

RAG（Retrieval-Augmented Generation，检索增强生成）是让大模型利用外部知识库回答问题的技术。它解决了大模型的知识截断和幻觉问题。

10.1 RAG 基本原理

RAG 的工作流程：

1. 文档处理：将文档切分为小块（chunks）
2. 向量化：使用嵌入模型将文档块转换为向量
3. 存储：将向量存入向量数据库
4. 检索：用户提问时，将问题向量化，在数据库中检索最相关的文档块
5. 生成：将检索到的文档块和用户问题一起发送给大模型生成回答

10.2 环境准备

# 安装依赖
pip install langchain langchain-community langchain-ollama
pip install chromadb sentence-transformers
pip install pypdf docx2txt unstructured

10.3 向量数据库选型

数据库	特点	适用场景
ChromaDB	轻量级，Python原生	个人项目、原型开发
FAISS	Facebook开源，高性能	大规模向量检索
Milvus	分布式，生产级	企业级应用
Qdrant	Rust实现，高性能	高性能需求
Weaviate	GraphQL接口	需要复杂查询

10.4 使用 LangChain 搭建 RAG

# rag_basic.py - 基础 RAG 系统
from langchain_community.document_loaders import (
    PyPDFLoader,
    DirectoryLoader,
    TextLoader,
)
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.vectorstores import Chroma
from langchain_ollama import OllamaEmbeddings, ChatOllama
from langchain.chains import RetrievalQA
from langchain.prompts import PromptTemplate

# 1. 加载文档
def load_documents(doc_dir):
    """加载目录中的所有文档"""
    loaders = {
        ".pdf": PyPDFLoader,
        ".txt": TextLoader,
        ".md": TextLoader,
    }
    
    documents = []
    for ext, loader_cls in loaders.items():
        loader = DirectoryLoader(
            doc_dir,
            glob=f"**/*{ext}",
            loader_cls=loader_cls,
            show_progress=True,
        )
        documents.extend(loader.load())
    
    print(f"加载了 {len(documents)} 个文档")
    return documents

# 2. 文档切分
def split_documents(documents, chunk_size=1000, chunk_overlap=200):
    """将文档切分为小块"""
    splitter = RecursiveCharacterTextSplitter(
        chunk_size=chunk_size,
        chunk_overlap=chunk_overlap,
        length_function=len,
        separators=["\n\n", "\n", "。", "！", "？", ".", "!", "?", " "],
    )
    chunks = splitter.split_documents(documents)
    print(f"切分为 {len(chunks)} 个文档块")
    return chunks

# 3. 创建向量数据库
def create_vectorstore(chunks, persist_dir="./chroma_db"):
    """创建并持久化向量数据库"""
    embeddings = OllamaEmbeddings(model="qwen2.5:7b")
    
    vectorstore = Chroma.from_documents(
        documents=chunks,
        embedding=embeddings,
        persist_directory=persist_dir,
    )
    
    print(f"向量数据库已创建，保存在: {persist_dir}")
    return vectorstore

# 4. 创建 RAG 链
def create_rag_chain(vectorstore):
    """创建 RAG 问答链"""
    llm = ChatOllama(
        model="qwen2.5:7b",
        temperature=0.3,
        num_predict=2048,
    )
    
    prompt_template = """基于以下上下文信息回答问题。如果上下文中没有相关信息，请说明你不确定。

上下文：
{context}

问题：{question}

回答："""
    
    prompt = PromptTemplate(
        template=prompt_template,
        input_variables=["context", "question"],
    )
    
    qa_chain = RetrievalQA.from_chain_type(
        llm=llm,
        chain_type="stuff",
        retriever=vectorstore.as_retriever(
            search_type="similarity",
            search_kwargs={"k": 4},
        ),
        chain_type_kwargs={"prompt": prompt},
        return_source_documents=True,
    )
    
    return qa_chain

# 主程序
if __name__ == "__main__":
    # 加载文档
    documents = load_documents("./documents")
    
    # 切分文档
    chunks = split_documents(documents)
    
    # 创建向量数据库
    vectorstore = create_vectorstore(chunks)
    
    # 创建 RAG 链
    qa_chain = create_rag_chain(vectorstore)
    
    # 交互式问答
    while True:
        question = input("\n请输入问题（输入 'quit' 退出）：")
        if question.lower() == "quit":
            break
        
        result = qa_chain.invoke({"query": question})
        
        print(f"\n回答：{result['result']}")
        print(f"\n参考来源：")
        for doc in result["source_documents"]:
            print(f"  - {doc.metadata.get('source', '未知')}")

10.5 文档处理流水线

# document_pipeline.py - 完整的文档处理流水线
import os
from pathlib import Path
from langchain_community.document_loaders import (
    PyPDFLoader,
    Docx2txtLoader,
    TextLoader,
    CSVLoader,
    UnstructuredMarkdownLoader,
)

class DocumentProcessor:
    """文档处理流水线"""
    
    def __init__(self, chunk_size=1000, chunk_overlap=200):
        self.chunk_size = chunk_size
        self.chunk_overlap = chunk_overlap
        self.loaders = {
            ".pdf": PyPDFLoader,
            ".docx": Docx2txtLoader,
            ".txt": TextLoader,
            ".csv": CSVLoader,
            ".md": UnstructuredMarkdownLoader,
        }
    
    def load_file(self, file_path):
        """加载单个文件"""
        ext = Path(file_path).suffix.lower()
        loader_cls = self.loaders.get(ext)
        
        if not loader_cls:
            print(f"不支持的文件格式: {ext}")
            return []
        
        try:
            loader = loader_cls(str(file_path))
            docs = loader.load()
            # 添加元数据
            for doc in docs:
                doc.metadata["source"] = str(file_path)
                doc.metadata["file_type"] = ext
            return docs
        except Exception as e:
            print(f"加载文件失败 {file_path}: {e}")
            return []
    
    def load_directory(self, dir_path):
        """加载目录中的所有文件"""
        documents = []
        dir_path = Path(dir_path)
        
        for file_path in dir_path.rglob("*"):
            if file_path.is_file() and file_path.suffix.lower() in self.loaders:
                docs = self.load_file(file_path)
                documents.extend(docs)
        
        print(f"共加载 {len(documents)} 个文档块")
        return documents
    
    def split_documents(self, documents):
        """智能切分文档"""
        from langchain.text_splitter import RecursiveCharacterTextSplitter
        
        splitter = RecursiveCharacterTextSplitter(
            chunk_size=self.chunk_size,
            chunk_overlap=self.chunk_overlap,
            length_function=len,
            separators=["\n\n", "\n", "。", "！", "？", "；", ".", "!", "?", ";", " "],
        )
        
        chunks = splitter.split_documents(documents)
        print(f"切分为 {len(chunks)} 个文档块")
        return chunks

# 使用示例
processor = DocumentProcessor(chunk_size=800, chunk_overlap=150)
docs = processor.load_directory("./my_documents")
chunks = processor.split_documents(docs)

10.6 检索优化

# retrieval_optimization.py - 检索策略优化
from langchain.retrievers import (
    ContextualCompressionRetriever,
    EnsembleRetriever,
)
from langchain.retrievers.document_compressors import CrossEncoderReranker
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
from langchain_community.vectorstores import Chroma

def create_optimized_retriever(vectorstore, llm):
    """创建优化的检索器"""
    
    # 1. 基础相似度检索
    similarity_retriever = vectorstore.as_retriever(
        search_type="similarity",
        search_kwargs={"k": 10},
    )
    
    # 2. MMR 检索（最大边际相关性，减少冗余）
    mmr_retriever = vectorstore.as_retriever(
        search_type="mmr",
        search_kwargs={"k": 6, "fetch_k": 20, "lambda_mult": 0.7},
    )
    
    # 3. 重排序（使用交叉编码器精排）
    cross_encoder = HuggingFaceCrossEncoder(model_name="BAAI/bge-reranker-v2-m3")
    reranker = CrossEncoderReranker(model=cross_encoder, top_n=4)
    
    compression_retriever = ContextualCompressionRetriever(
        base_compressor=reranker,
        base_retriever=similarity_retriever,
    )
    
    # 4. 集成检索（结合多种检索策略）
    ensemble_retriever = EnsembleRetriever(
        retrievers=[similarity_retriever, mmr_retriever],
        weights=[0.6, 0.4],
    )
    
    return compression_retriever  # 或 ensemble_retriever

---

11. 性能优化

11.1 GPU 显存优化

# 1. 使用量化减少显存占用
# Q4_K_M 量化: 7B 模型只需 ~4GB 显存
ollama pull qwen2.5:7b-q4_K_M

# 2. 控制上下文长度
# 减少上下文长度可以显著降低 KV Cache 显存
export OLLAMA_NUM_CTX=4096  # 默认可能是更大的值

# 3. 使用 Flash Attention（vLLM）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --enable-chunked-prefill \
  --max-num-batched-tokens 512

# 4. 使用 bitsandbytes 4-bit 加载
from transformers import AutoModelForCausalLM, BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,  # 双重量化，进一步减少显存
)

model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    quantization_config=bnb_config,
    device_map="auto",
)

11.2 KV Cache 管理

KV Cache 是推理过程中存储注意力键值对的缓存，是显存占用的主要来源之一。

# vLLM KV Cache 优化
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --gpu-memory-utilization 0.92 \
  --kv-cache-dtype fp8 \           # 使用 FP8 KV Cache
  --max-model-len 8192 \           # 限制最大序列长度
  --enable-prefix-caching          # 启用前缀缓存

# llama.cpp KV Cache 优化
./build/bin/llama-cli -m model.gguf \
  -c 4096 \          # 上下文长度（直接决定KV Cache大小）
  -ctk q8_0 \        # KV Cache 量化为 Q8
  --flash-attn        # 使用 Flash Attention

11.3 批处理策略

# 批量处理多个请求
import asyncio
from openai import AsyncOpenAI

async def batch_process(prompts, model="Qwen/Qwen2.5-7B-Instruct"):
    client = AsyncOpenAI(base_url="http://localhost:8000/v1", api_key="token")
    
    async def process_one(prompt):
        response = await client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": prompt}],
            max_tokens=512,
        )
        return response.choices[0].message.content
    
    # 并发处理
    tasks = [process_one(p) for p in prompts]
    results = await asyncio.gather(*tasks)
    return results

# 使用
prompts = ["问题1", "问题2", "问题3", "问题4", "问题5"]
results = asyncio.run(batch_process(prompts))

11.4 模型并行

# 张量并行（多GPU）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 2 \       # 使用2张GPU
  --gpu-memory-utilization 0.9

# 流水线并行（vLLM 支持）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-72B-Instruct \
  --tensor-parallel-size 2 \
  --pipeline-parallel-size 2       # 4张GPU，2x2并行

11.5 推理加速技巧

# 1. 使用 Flash Attention
# vLLM 默认启用
# llama.cpp: --flash-attn

# 2. 使用 CUDA Graph
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --enforce-eager  # 禁用CUDA Graph（调试用）
  # 默认启用 CUDA Graph

# 3. 调整批处理参数
--max-num-seqs 256              # 最大并发序列数
--max-num-batched-tokens 8192   # 最大批处理token数

# 4. 使用 Speculative Decoding（投机解码）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --speculative-model Qwen/Qwen2.5-0.5B-Instruct \
  --num-speculative-tokens 5

# 5. 预编译模型（减少首次加载时间）
python -m vllm.entrypoints.openai.api_server \
  --model Qwen/Qwen2.5-7B-Instruct \
  --load-format auto

11.6 系统级优化

# 1. 设置环境变量
export CUDA_VISIBLE_DEVICES=0          # 指定GPU
export PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512  # 减少内存碎片

# 2. 清理GPU显存
import torch
torch.cuda.empty_cache()

# 3. 监控GPU使用
nvidia-smi -l 1  # 每秒刷新

# 4. 使用更快的存储
# 将模型放在 NVMe SSD 上

# 5. 调整系统参数（Linux）
sudo sysctl -w vm.overcommit_memory=1
echo 'ulimit -n 65535' >> ~/.bashrc

---

12. 实战项目：搭建本地 AI 编程助手

在这一章中，我们将综合前面学到的所有知识，搭建一个功能完整的本地 AI 编程助手，类似于 GitHub Copilot。

12.1 项目概述

我们的 AI 编程助手将具备以下功能：

• 代码补全：根据上下文自动补全代码
• 代码解释：解释代码的功能和逻辑
• 代码重构：优化和重构现有代码
• 错误修复：分析并修复代码错误
• 单元测试生成：自动生成单元测试
• 代码审查：审查代码质量并提供建议

12.2 技术架构

┌─────────────────────────────────────────┐
│           VS Code 插件/命令行            │
├─────────────────────────────────────────┤
│            API Gateway (FastAPI)         │
├──────────┬──────────┬───────────────────┤
│ 代码补全  │ 代码解释  │   代码审查        │
│ (快速)    │ (详细)    │   (深度)          │
├──────────┴──────────┴───────────────────┤
│        模型层 (Ollama / vLLM)           │
│   ┌─────────┐  ┌─────────┐              │
│   │ Code模型 │  │ 通用模型 │              │
│   │ 7B 快速  │  │ 14B 精准 │              │
│   └─────────┘  └─────────┘              │
├─────────────────────────────────────────┤
│          RAG 知识库 (可选)               │
│    项目文档 / API 文档 / 代码规范         │
└─────────────────────────────────────────┘

12.3 模型选择与部署

# 步骤 1: 安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 步骤 2: 下载代码专用模型
ollama pull qwen2.5-coder:7b       # 快速代码补全
ollama pull qwen2.5-coder:14b      # 高质量代码生成（如果有足够显存）
ollama pull deepseek-r1:8b          # 复杂推理任务

# 步骤 3: 创建自定义代码助手模型
cat > Modelfile.coder << 'EOF'
FROM qwen2.5-coder:7b

SYSTEM """
You are an expert programming assistant. Follow these rules:
1. Write clean, well-documented code
2. Follow language-specific best practices and conventions
3. Include error handling and edge case considerations
4. Provide concise explanations in Chinese when asked
5. Use English for code comments
6. When generating code, always consider:
   - Type safety
   - Performance implications
   - Security best practices
   - Testability
"""

PARAMETER temperature 0.2
PARAMETER top_p 0.95
PARAMETER num_ctx 8192
PARAMETER num_predict 4096
PARAMETER repeat_penalty 1.05
PARAMETER stop "```"
EOF

ollama create code-assistant -f Modelfile.coder

# 步骤 4: 创建快速补全模型
cat > Modelfile.completion << 'EOF'
FROM qwen2.5-coder:7b

SYSTEM "Complete the following code. Output only the code completion, no explanations."

PARAMETER temperature 0.1
PARAMETER top_p 0.9
PARAMETER num_ctx 4096
PARAMETER num_predict 1024
PARAMETER repeat_penalty 1.0
PARAMETER stop ["\n\n", "```", "---"]
EOF

ollama create code-completion -f Modelfile.completion

12.4 后端 API 开发

# server.py - AI 编程助手后端
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from openai import OpenAI
from typing import Optional
import uvicorn

app = FastAPI(title="本地 AI 编程助手")

# Ollama 客户端
client = OpenAI(
    base_url="http://localhost:11434/v1",
    api_key="ollama"
)

class CompletionRequest(BaseModel):
    prefix: str          # 光标前的代码
    suffix: str = ""     # 光标后的代码
    language: str = ""   # 编程语言
    max_tokens: int = 256

class ChatRequest(BaseModel):
    message: str
    code_context: str = ""
    language: str = ""
    mode: str = "chat"   # chat / explain / refactor / fix / test

class CodeRequest(BaseModel):
    code: str
    language: str = ""
    task: str = ""       # 任务描述

# 代码补全
@app.post("/api/completion")
async def code_completion(req: CompletionRequest):
    """代码补全 - 快速响应"""
    prompt = f"""```{req.language}
{req.prefix}"""
    
    try:
        response = client.completions.create(
            model="code-completion",
            prompt=prompt,
            max_tokens=req.max_tokens,
            temperature=0.1,
            stop=["\n\n", "```"],
        )
        completion = response.choices[0].text
        return {"completion": completion}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# 对话式编程助手
@app.post("/api/chat")
async def code_chat(req: ChatRequest):
    """对话式编程助手"""
    
    mode_prompts = {
        "chat": "你是一个专业的编程助手。用中文回答，代码用英文注释。",
        "explain": "详细解释以下代码的功能、逻辑和关键点。用中文回答。",
        "refactor": "重构以下代码，提高代码质量、可读性和性能。说明改进点。",
        "fix": "分析以下代码中的错误并修复。解释错误原因和修复方案。",
        "test": "为以下代码生成完整的单元测试。使用 pytest 框架。",
    }
    
    system_prompt = mode_prompts.get(req.mode, mode_prompts["chat"])
    
    messages = [
        {"role": "system", "content": system_prompt},
    ]
    
    if req.code_context:
        messages.append({
            "role": "user",
            "content": f"编程语言: {req.language}\n\n代码:\n```\n{req.code_context}\n```\n\n{req.message}"
        })
    else:
        messages.append({"role": "user", "content": req.message})
    
    try:
        response = client.chat.completions.create(
            model="code-assistant",
            messages=messages,
            temperature=0.3,
            max_tokens=2048,
        )
        return {"response": response.choices[0].message.content}
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

# 代码审查
@app.post("/api/review")
async def code_review(req: CodeRequest):
    """代码审查"""
    prompt = f"""请审查以下{req.language}代码，从以下方面给出评价和改进建议：

1. **代码质量**：命名规范、代码结构、可读性
2. **性能**：是否有性能瓶颈或优化空间
3. **安全性**：是否存在安全隐患
4. **最佳实践**：是否遵循语言和框架的最佳实践
5. **错误处理**：异常处理是否完善
6. **建议改进**：具体的改进方案和代码示例

代码：
```{req.language}
{req.code}

"""

try:
    response = client.chat.completions.create(
        model="code-assistant",
        messages=[
            {"role": "system", "content": "你是一个资深的代码审查专家。给出详细、专业、有建设性的审查意见。"},
            {"role": "user", "content": prompt}
        ],
        temperature=0.3,
        max_tokens=2048,
    )
    return {"review": response.choices[0].message.content}
except Exception as e:
    raise HTTPException(status_code=500, detail=str(e))

生成代码

@app.post("/api/generate") async def generate_code(req: CodeRequest): "根据描述生成代码" prompt = f"""用 实现以下需求：

要求：

1. 代码完整可运行

2. 包含必要的导入

3. 添加详细注释

4. 考虑错误处理

5. 遵循最佳实践 """

   try: response = client.chat.completions.create( model="code-assistant", messages=[ {"role": "system", "content": "你是一个专业的全栈开发工程师。生成高质量、可生产的代码。"}, {"role": "user", "content": prompt} ], temperature=0.3, max_tokens=4096, ) return {"code": response.choices[0].message.content} except Exception as e: raise HTTPException(status_code=500, detail=str(e))

if name == "main": uvicorn.run(app, host="0.0.0.0", port=8080)

### 12.5 命令行客户端

```python
# cli.py - 命令行客户端
import requests
import sys
import argparse
from rich.console import Console
from rich.markdown import Markdown
from rich.syntax import Syntax

console = Console()
API_BASE = "http://localhost:8080/api"

def chat(message, code="", language="", mode="chat"):
    """对话模式"""
    response = requests.post(f"{API_BASE}/chat", json={
        "message": message,
        "code_context": code,
        "language": language,
        "mode": mode,
    })
    
    if response.status_code == 200:
        result = response.json()["response"]
        console.print(Markdown(result))
    else:
        console.print(f"[red]错误: {response.text}[/red]")

def complete(prefix, suffix="", language=""):
    """代码补全"""
    response = requests.post(f"{API_BASE}/completion", json={
        "prefix": prefix,
        "suffix": suffix,
        "language": language,
    })
    
    if response.status_code == 200:
        completion = response.json()["completion"]
        console.print(Syntax(prefix + completion, language or "text"))
    else:
        console.print(f"[red]错误: {response.text}[/red]")

def review(code, language=""):
    """代码审查"""
    response = requests.post(f"{API_BASE}/review", json={
        "code": code,
        "language": language,
    })
    
    if response.status_code == 200:
        review_result = response.json()["review"]
        console.print(Markdown(review_result))
    else:
        console.print(f"[red]错误: {response.text}[/red]")

def interactive_mode():
    """交互模式"""
    console.print("[bold green]本地 AI 编程助手 - 交互模式[/bold green]")
    console.print("输入代码或问题，输入 'quit' 退出\n")
    
    while True:
        try:
            user_input = console.input("[bold blue]>>> [/bold blue]")
            
            if user_input.lower() in ["quit", "exit", "q"]:
                break
            
            if user_input.startswith("/review"):
                code = user_input[7:].strip()
                if not code:
                    console.print("[yellow]请输入要审查的代码[/yellow]")
                    continue
                review(code)
            elif user_input.startswith("/explain"):
                code = user_input[8:].strip()
                chat("请解释这段代码", code=code, mode="explain")
            elif user_input.startswith("/fix"):
                code = user_input[4:].strip()
                chat("请修复这段代码中的错误", code=code, mode="fix")
            elif user_input.startswith("/test"):
                code = user_input[5:].strip()
                chat("请为这段代码生成单元测试", code=code, mode="test")
            else:
                chat(user_input)
            
            console.print()
        except KeyboardInterrupt:
            break
        except EOFError:
            break

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="本地 AI 编程助手")
    parser.add_argument("--chat", "-c", help="对话模式")
    parser.add_argument("--review", "-r", help="代码审查")
    parser.add_argument("--interactive", "-i", action="store_true", help="交互模式")
    
    args = parser.parse_args()
    
    if args.interactive:
        interactive_mode()
    elif args.chat:
        chat(args.chat)
    elif args.review:
        review(args.review)
    else:
        interactive_mode()

12.6 VS Code 集成方案

// .vscode/tasks.json - VS Code 任务配置
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "AI: 解释代码",
      "type": "shell",
      "command": "python cli.py --chat '请解释选中的代码: ${selectedText}'",
      "problemMatcher": []
    },
    {
      "label": "AI: 代码审查",
      "type": "shell",
      "command": "python cli.py --review '${selectedText}'",
      "problemMatcher": []
    }
  ]
}

12.7 启动与使用

# 步骤 1: 启动 Ollama 服务
ollama serve &

# 步骤 2: 确认模型已下载
ollama list

# 步骤 3: 启动后端 API
pip install fastapi uvicorn openai rich
python server.py

# 步骤 4: 使用命令行客户端
# 交互模式
python cli.py --interactive

# 单次对话
python cli.py --chat "用Python写一个HTTP服务器"

# 代码审查
python cli.py --review "def add(a,b): return a+b"

# 步骤 5: 使用 curl 测试 API
curl http://localhost:8080/api/chat -H "Content-Type: application/json" -d '{
  "message": "用Python实现快速排序",
  "mode": "chat"
}'

curl http://localhost:8080/api/completion -H "Content-Type: application/json" -d '{
  "prefix": "def fibonacci(n):\n    ",
  "language": "python"
}'

12.8 进阶优化

# 1. 添加项目上下文（RAG）
# 将项目文档和代码规范加入知识库
# 在生成代码时自动参考项目规范

# 2. 添加缓存机制
from functools import lru_cache
import hashlib

cache = {}

def cached_completion(prefix, language):
    key = hashlib.md5(f"{prefix}:{language}".encode()).hexdigest()
    if key in cache:
        return cache[key]
    result = code_completion(prefix, language)
    cache[key] = result
    return result

# 3. 添加速率限制
from fastapi import Request
from fastapi.middleware.cors import CORSMiddleware
import time

request_times = []

@app.middleware("http")
async def rate_limit(request: Request, call_next):
    now = time.time()
    request_times[:] = [t for t in request_times if now - t < 60]
    
    if len(request_times) >= 30:  # 每分钟最多30个请求
        return JSONResponse(
            status_code=429,
            content={"error": "请求过于频繁，请稍后再试"}
        )
    
    request_times.append(now)
    response = await call_next(request)
    return response

# 4. 添加日志记录
import logging

logging.basicConfig(
    filename="assistant.log",
    level=logging.INFO,
    format="%(asctime)s - %(message)s"
)

@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    duration = time.time() - start
    logging.info(f"{request.method} {request.url.path} - {response.status_code} - {duration:.2f}s")
    return response

12.9 项目总结

通过这个实战项目，我们综合运用了前面学到的所有知识：

1. 模型部署：使用 Ollama 部署了代码专用模型
2. 自定义模型：通过 Modelfile 定制了代码助手的行为
3. API 开发：使用 FastAPI 构建了 RESTful API
4. 多模型策略：代码补全用小模型（快速），代码审查用大模型（精准）
5. RAG 知识库：可以扩展加入项目文档和代码规范
6. 性能优化：缓存、速率限制等生产级优化

这个项目的代码量不大，但功能完整。你可以在此基础上继续扩展：

• 开发 VS Code 插件
• 添加 Git 集成（自动生成 commit message）
• 添加代码搜索功能
• 集成更多编程语言的特定优化
• 添加团队协作功能

---

附录 A：常见问题解答

Q1: 我的显存不够怎么办？

# 方案 1: 使用更小的模型
ollama pull qwen2.5:3b   # 3B 只需约 2GB 显存

# 方案 2: 使用更激进的量化
ollama pull qwen2.5:7b-q3_K_M  # 3-bit 量化

# 方案 3: 使用 CPU 推理
# Ollama 会自动在显存不足时回退到 CPU
export OLLAMA_NUM_GPU=0  # 强制使用 CPU

# 方案 4: 使用云 GPU
# 在 AutoDL 等平台租用 GPU

Q2: 模型回答质量不好怎么办？

# 1. 尝试更大的模型
ollama pull qwen2.5:14b  # 14B 通常比 7B 质量好很多

# 2. 优化提示词
# 不好的提示词: "写代码"
# 好的提示词: "用Python写一个函数，输入一个列表，返回去重后按大小排序的结果，要求使用类型注解"

# 3. 使用系统提示词
ollama run qwen2.5:7b --system "你是一个资深的Python开发专家，回答要详细、准确、包含代码示例。"

# 4. 调整参数
# 降低温度可以让回答更确定
# 增加上下文长度可以让模型理解更多背景

Q3: 推理速度太慢怎么办？

# 1. 使用 GPU 加速
# 确保安装了 CUDA 和 GPU 驱动
nvidia-smi  # 检查 GPU 状态

# 2. 减少上下文长度
export OLLAMA_NUM_CTX=2048  # 默认可能是 4096 或更大

# 3. 使用更小的模型
# 3B 模型比 7B 快 2-3 倍

# 4. 使用量化模型
# Q4 比 Q8 快，Q8 比 FP16 快

# 5. 如果是 Mac，确保使用 Metal 加速
# Ollama 在 Mac 上默认使用 Metal

Q4: 如何在多台电脑之间共享模型？

# 方案 1: 使用 Ollama 的远程访问
export OLLAMA_HOST=0.0.0.0:11434
# 其他电脑通过 http://你的IP:11434 访问

# 方案 2: 使用 vLLM 的 API Server
python -m vllm.entrypoints.openai.api_server \
  --host 0.0.0.0 --port 8000

# 方案 3: 复制模型文件
# Ollama 模型存储在 ~/.ollama/models/
# 可以直接复制这个目录到其他电脑

Q5: 如何更新模型到最新版本？

# Ollama 会自动检查更新
ollama pull qwen2.5:7b  # 如果有新版本会自动下载

# 查看当前版本
ollama show qwen2.5:7b

# 强制重新下载
ollama rm qwen2.5:7b
ollama pull qwen2.5:7b

---

附录 B：学习资源

官方文档

• Ollama: https://ollama.com
• llama.cpp: https://github.com/ggerganov/llama.cpp
• vLLM: https://docs.vllm.ai
• Open WebUI: https://docs.openwebui.com

模型下载

• Hugging Face: https://huggingface.co
• ModelScope（国内）: https://www.modelscope.cn
• Ollama 模型库: https://ollama.com/library

社区资源

• r/LocalLLaMA (Reddit): https://www.reddit.com/r/LocalLLaMA
• Hugging Face 论坛: https://discuss.huggingface.co
• LangChain 文档: https://python.langchain.com

推荐阅读

• 《大语言模型》- 综述性教材
• Attention Is All You Need - Transformer 原始论文
• LoRA 论文 - Low-Rank Adaptation of Large Language Models
• RAG 论文 - Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks

---

结语

恭喜你完成了这个开源大模型本地部署教程！让我们回顾一下你学到的内容：

1. 为什么本地部署：隐私保护、成本控制、离线使用、自由定制
2. 模型选型：Llama、Qwen、DeepSeek 等主流模型的特点和适用场景
3. 硬件规划：GPU 显存需求、CPU 推理、云 GPU 方案
4. Ollama 部署：最简单的本地模型部署方案
5. llama.cpp：底层推理引擎，极致灵活
6. vLLM：高性能生产级推理引擎
7. Open WebUI：类 ChatGPT 的图形界面
8. 模型量化：在有限硬件上运行更大模型
9. LoRA 微调：让模型适应你的特定需求
10. RAG 知识库：让模型利用你的私有知识
11. 性能优化：榨干硬件的每一滴性能
12. 实战项目：搭建完整的 AI 编程助手

接下来你可以：

• 根据自己的硬件选择合适的模型开始使用
• 尝试微调模型适应你的专业领域
• 搭建 RAG 知识库处理你的私有文档
• 开发更多有趣的 AI 应用
• 关注开源社区的最新动态，新模型和工具层出不穷

本地部署大模型的世界充满可能性。随着开源模型的不断进步和硬件成本的持续下降，每个人都能拥有自己的 AI 助手。开始探索吧！

---

本教程最后更新：2025年5月 如有问题或建议，欢迎反馈