Llama 3 本地部署与微调完全教程

本文全面介绍 Llama 3 系列模型的本地部署、量化、微调与应用实战，适合希望在自有硬件上运行大语言模型的开发者和研究者。

---

目录

1. Llama 3 系列模型概述
2. 硬件需求规划
3. 部署方案一：Ollama
4. 部署方案二：vLLM
5. 部署方案三：llama.cpp
6. Open WebUI 图形界面
7. 模型量化实战
8. LoRA/QLoRA 微调实战
9. RAG 本地知识库构建
10. Agent 应用开发
11. 性能优化策略
12. 与 Qwen/DeepSeek 对比
13. 常见问题与排错
14. 总结与资源

---

1. Llama 3 系列模型概述

1.1 模型家族

Llama 3 是 Meta 于 2024 年发布的新一代开源大语言模型系列，包含多个规格：

模型	参数量	上下文长度	发布时间	训练数据量
Llama 3 8B	8B	8K	2024-04	15T tokens
Llama 3 70B	70B	8K	2024-04	15T tokens
Llama 3.1 8B	8B	128K	2024-07	15T+ tokens
Llama 3.1 70B	70B	128K	2024-07	15T+ tokens
Llama 3.1 405B	405B	128K	2024-07	15T+ tokens
Llama 3.2 1B	1B	128K	2024-09	-
Llama 3.2 3B	3B	128K	2024-09	-
Llama 3.2 11B Vision	11B	128K	2024-09	-
Llama 3.2 90B Vision	90B	128K	2024-09	-
Llama 3.3 70B	70B	128K	2024-12	-

1.2 核心架构特点

Llama 3 采用标准的 Transformer Decoder-Only 架构，但在多个方面进行了优化：

• 分词器升级：从 Llama 2 的 32K 词表扩展到 128K 词表，大幅提升多语言编码效率
• GQA（Grouped Query Attention）：8B 模型使用 8 个 KV Head，70B 使用 8 个 KV Head，平衡性能与显存
• RoPE 位置编码：支持长达 128K 的上下文窗口（Llama 3.1+）
• SwiGLU 激活函数：替代传统的 ReLU/GELU，提升模型表达能力
• RMSNorm：Pre-Norm 配置，训练更稳定

Llama 3 8B 架构示意：
┌─────────────────────────────┐
│     Token Embedding (128K)  │
├─────────────────────────────┤
│  × 32 Transformer Blocks    │
│  ┌───────────────────────┐  │
│  │ RMSNorm               │  │
│  │ GQA (32Q / 8KV Heads) │  │
│  │ + RoPE                │  │
│  │ Residual Connection   │  │
│  │ RMSNorm               │  │
│  │ SwiGLU FFN            │  │
│  │ Residual Connection   │  │
│  └───────────────────────┘  │
├─────────────────────────────┤
│     RMSNorm                 │
│     Linear (Output Head)    │
└─────────────────────────────┘

1.3 能力矩阵

能力领域	8B 表现	70B 表现	405B 表现
代码生成	★★★☆	★★★★	★★★★★
数学推理	★★★☆	★★★★	★★★★★
多语言	★★★☆	★★★★	★★★★★
长文本	★★★☆	★★★★	★★★★★
指令遵循	★★★★	★★★★★	★★★★★
工具调用	★★★☆	★★★★	★★★★★

---

2. 硬件需求规划

2.1 显存需求估算

选择硬件前，需要了解模型的显存需求。以下公式可以快速估算：

显存 (GB) ≈ 参数量 (B) × 每参数字节数

FP32: 每参数 4 字节
FP16/BF16: 每参数 2 字节
INT8: 每参数 1 字节
INT4: 每参数 0.5 字节

模型	FP16	INT8	INT4 (GPTQ/AWQ)	GGUF Q4_K_M
1B	~2 GB	~1 GB	~0.7 GB	~0.8 GB
3B	~6 GB	~3 GB	~2 GB	~2.2 GB
8B	~16 GB	~8 GB	~5 GB	~5.5 GB
70B	~140 GB	~70 GB	~40 GB	~42 GB
405B	~810 GB	~405 GB	~210 GB	~230 GB

注意：以上为纯模型权重的估算，实际运行还需额外显存用于 KV Cache、激活值等。建议预留 20%-30% 的额外空间。

2.2 推荐硬件配置

入门级（8B 模型）：

• GPU：NVIDIA RTX 3060 12GB / RTX 4060 Ti 16GB
• 内存：32GB DDR4/DDR5
• 存储：500GB NVMe SSD
• 预算：约 5000-8000 元

进阶级（8B 全精度 / 70B 量化）：

• GPU：NVIDIA RTX 4090 24GB / A6000 48GB
• 内存：64GB DDR5
• 存储：1TB NVMe SSD
• 预算：约 15000-30000 元

专业级（70B 全精度 / 405B 量化）：

• GPU：2× NVIDIA A100 80GB / 4× RTX 4090
• 内存：256GB DDR5
• 存储：2TB NVMe SSD
• 预算：约 100000+ 元

纯 CPU 方案（llama.cpp）：

• CPU：高主频多核（如 AMD Ryzen 9 7950X / Intel i9-14900K）
• 内存：64GB+（需容纳完整模型）
• 存储：NVMe SSD
• 适用：8B INT4 量化模型，速度约 5-15 tokens/s

2.3 云端替代方案

如果本地硬件不足，可考虑以下云 GPU 方案：

平台	GPU 类型	价格（约）	适用场景
AutoDL	A100 80GB	~5 元/小时	70B 微调
阿里云 PAI	V100/A10	~3-8 元/小时	通用训练
AWS p4d	A100 40GB	~$32/小时	企业级
Vast.ai	各类 GPU	~$0.2-2/小时	性价比高

---

3. 部署方案一：Ollama

Ollama 是目前最简单的本地 LLM 部署工具，支持一键拉取和运行模型。

3.1 安装 Ollama

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

# macOS 也可以用 Homebrew
brew install ollama

# 验证安装
ollama --version

3.2 拉取并运行 Llama 3

# 拉取 Llama 3 8B（默认 Q4 量化）
ollama pull llama3

# 拉取 Llama 3.1 8B
ollama pull llama3.1

# 拉取 Llama 3.3 70B（需要较大显存）
ollama pull llama3.3:70b

# 运行模型
ollama run llama3

# 交互式对话
>>> 你好，请介绍一下你自己。

3.3 自定义模型配置

创建 Modelfile 进行自定义：

# Modelfile
FROM llama3.1:8b

# 系统提示词
SYSTEM """
你是一个专业的中文AI助手，擅长编程和技术问答。
请用简洁明了的中文回答问题。
"""

# 模型参数
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER top_k 40
PARAMETER num_ctx 8192
PARAMETER repeat_penalty 1.1

# 停止词
PARAMETER stop "<|eot_id|>"
PARAMETER stop "<|end|>"

# 创建自定义模型
ollama create my-llama3 -f Modelfile

# 运行自定义模型
ollama run my-llama3

3.4 Ollama API 调用

Ollama 提供了兼容 OpenAI 格式的 API：

# 启动 Ollama 服务（默认端口 11434）
ollama serve

# 使用 curl 调用
curl http://localhost:11434/api/generate -d '{
  "model": "llama3",
  "prompt": "用Python写一个快速排序",
  "stream": false
}'

# OpenAI 兼容格式
curl http://localhost:11434/v1/chat/completions -d '{
  "model": "llama3",
  "messages": [
    {"role": "system", "content": "你是一个有帮助的助手"},
    {"role": "user", "content": "什么是量子计算？"}
  ]
}'

Python 调用示例：

import requests
import json

def chat_with_ollama(prompt, model="llama3"):
    url = "http://localhost:11434/api/chat"
    payload = {
        "model": model,
        "messages": [{"role": "user", "content": prompt}],
        "stream": False
    }
    response = requests.post(url, json=payload)
    return response.json()["message"]["content"]

# 使用 OpenAI 兼容接口
from openai import OpenAI

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

response = client.chat.completions.create(
    model="llama3",
    messages=[
        {"role": "system", "content": "你是一个Python专家"},
        {"role": "user", "content": "解释装饰器的原理"}
    ],
    temperature=0.7
)
print(response.choices[0].message.content)

---

4. 部署方案二：vLLM

vLLM 是高性能的 LLM 推理引擎，支持 PagedAttention、连续批处理等优化，适合生产环境。

4.1 安装 vLLM

# 安装 vLLM（需要 CUDA 环境）
pip install vllm

# 或从源码安装（获取最新特性）
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

4.2 启动推理服务

# 启动 OpenAI 兼容的 API 服务
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-8B-Instruct \
    --host 0.0.0.0 \
    --port 8000 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.9 \
    --dtype auto \
    --trust-remote-code

# 多 GPU 张量并行（70B 模型）
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-70B-Instruct \
    --tensor-parallel-size 2 \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.95

4.3 Python 客户端

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token-abc123"  # vLLM 不验证，但需要非空值
)

# 基本对话
response = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    messages=[
        {"role": "user", "content": "写一个二分查找的Python实现"}
    ],
    temperature=0.7,
    max_tokens=1024
)
print(response.choices[0].message.content)

# 流式输出
stream = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    messages=[{"role": "user", "content": "讲一个故事"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

4.4 vLLM 高级配置

from vllm import LLM, SamplingParams

# 直接使用 vLLM Python API
llm = LLM(
    model="meta-llama/Meta-Llama-3.1-8B-Instruct",
    tensor_parallel_size=1,
    gpu_memory_utilization=0.9,
    max_model_len=8192,
    enforce_eager=True,  # 禁用 CUDA Graph，减少显存占用
    quantization="awq",  # 使用 AWQ 量化
)

sampling_params = SamplingParams(
    temperature=0.7,
    top_p=0.9,
    max_tokens=512,
    repetition_penalty=1.1
)

prompts = [
    "用Python实现冒泡排序",
    "解释什么是Docker",
    "写一首关于春天的诗"
]

outputs = llm.generate(prompts, sampling_params)
for output in outputs:
    print(f"Prompt: {output.prompt[:50]}...")
    print(f"Output: {output.outputs[0].text}")
    print("---")

---

5. 部署方案三：llama.cpp

llama.cpp 是 Georgi Gerganov 开发的纯 C/C++ 推理引擎，支持 CPU 和多种 GPU 后端，是量化模型 GGUF 格式的标准运行时。

5.1 编译安装

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

# CPU 编译
make -j$(nproc)

# CUDA 加速编译
make -j$(nproc) GGML_CUDA=1

# Metal 加速（macOS Apple Silicon）
make -j$(nproc) GGML_METAL=1

# Vulkan 加速（AMD/Intel GPU）
make -j$(nproc) GGML_VULKAN=1

5.2 下载 GGUF 模型

# 从 Hugging Face 下载预量化模型
# 推荐使用 huggingface-cli
pip install huggingface_hub

# 下载 Llama 3.1 8B 的 Q4_K_M 量化版本
huggingface-cli download \
    bartowski/Meta-Llama-3.1-8B-Instruct-GGUF \
    Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    --local-dir ./models/

# 或使用 wget（单文件下载）
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    -O ./models/llama3.1-8b-q4km.gguf

5.3 运行推理

# 交互式对话
./llama-cli \
    -m ./models/llama3.1-8b-q4km.gguf \
    -c 4096 \
    -t 8 \
    --temp 0.7 \
    -ngl 99 \
    -p "<|begin_of_text|><|start_header_id|>user<|end_header_id|>\n\n你好，请介绍一下自己。<|eot_id|><|start_header_id|>assistant<|end_header_id|>\n\n"

# 启动 HTTP 服务（兼容 OpenAI API）
./llama-server \
    -m ./models/llama3.1-8b-q4km.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    -c 4096 \
    -ngl 99 \
    -t 8

参数说明：

参数	说明
-m	模型文件路径
-c	上下文长度
-t	CPU 线程数
-ngl	GPU 层数（99 表示全部上 GPU）
--temp	采样温度
-p	提示词（prompt）

5.4 模型转换与量化

# 将 HuggingFace 模型转为 GGUF 格式
python convert_hf_to_gguf.py \
    meta-llama/Meta-Llama-3.1-8B-Instruct \
    --outfile ./models/llama3.1-8b-f16.gguf \
    --outtype f16

# 对 GGUF 模型进行量化
./llama-quantize \
    ./models/llama3.1-8b-f16.gguf \
    ./models/llama3.1-8b-q4km.gguf \
    Q4_K_M

常用量化类型对比：

量化类型	大小 (8B)	质量损失	推荐场景
Q2_K	~3.0 GB	较大	极端显存受限
Q3_K_M	~3.8 GB	中等	低显存设备
Q4_0	~4.5 GB	较小	基础量化
Q4_K_M	~5.0 GB	小	推荐默认
Q5_K_M	~5.9 GB	极小	质量优先
Q6_K	~6.6 GB	几乎无	接近原始质量
Q8_0	~8.5 GB	无	无损量化
F16	~16 GB	无	全精度

---

6. Open WebUI 图形界面

Open WebUI 提供了类似 ChatGPT 的图形界面，支持多种后端。

6.1 Docker 部署

# 使用 Docker 一键部署（连接 Ollama）
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

# 如果 Ollama 运行在本地，需要设置环境变量
docker run -d \
    -p 3000:8080 \
    -e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
    -v open-webui:/app/backend/data \
    --name open-webui \
    --restart always \
    ghcr.io/open-webui/open-webui:main

6.2 pip 安装

pip install open-webui

# 启动
open-webui serve --port 3000

6.3 功能概览

访问 http://localhost:3000，首次使用需注册管理员账号。Open WebUI 支持：

• 多模型管理：同时连接 Ollama、vLLM 等多个后端
• 对话管理：创建、编辑、导出对话历史
• RAG 集成：上传文档构建知识库
• Prompt 模板：创建和管理提示词模板
• 用户管理：多用户权限控制
• Web 搜索：集成搜索引擎进行实时搜索

---

7. 模型量化实战

7.1 GPTQ 量化

GPTQ 是基于二阶信息的训练后量化方法，在 INT4 精度下保持较好质量。

from transformers import AutoTokenizer
from optimum.gptq import GPTQQuantizer, load_quantized_model
import torch

model_id = "meta-llama/Meta-Llama-3.1-8B-Instruct"

# 加载 tokenizer
tokenizer = AutoTokenizer.from_pretrained(model_id)

# 准备校准数据
calibration_data = [
    "人工智能是计算机科学的一个分支",
    "机器学习通过数据驱动的方式",
    "深度学习使用多层神经网络",
    # ... 建议准备 128-256 条样本
]

# GPTQ 量化
quantizer = GPTQQuantizer(
    bits=4,
    dataset="c4",  # 或自定义校准数据
    group_size=128,
    desc_act=True,
)

# 执行量化并保存
quantizer.quantize_model(model_id, save_dir="./llama3-8b-gptq")
tokenizer.save_pretrained("./llama3-8b-gptq")

使用 AutoGPTQ 工具量化：

# 安装 AutoGPTQ
pip install auto-gptq

# 量化脚本
python -c "
from auto_gptq import AutoGPTQForCausalLM, BaseQuantizeConfig
from transformers import AutoTokenizer

model_id = 'meta-llama/Meta-Llama-3.1-8B-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)

# 使用校准数据量化
examples = [tokenizer('人工智能技术发展迅速', return_tensors='pt')]
model.quantize(examples)
model.save_quantized('./llama3-8b-gptq')
tokenizer.save_pretrained('./llama3-8b-gptq')
"

7.2 AWQ 量化

AWQ（Activation-aware Weight Quantization）保留对激活值重要的权重通道，通常比 GPTQ 更快且质量相当。

from awq import AutoAWQForCausalLM
from transformers import AutoTokenizer

model_id = "meta-llama/Meta-Llama-3.1-8B-Instruct"

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

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

# 执行量化
model.quantize(
    tokenizer,
    quant_config=quant_config,
    calib_data="pileval",  # 使用 Pile 验证集校准
)

# 保存量化模型
model.save_quantized("./llama3-8b-awq")
tokenizer.save_pretrained("./llama3-8b-awq")

7.3 GGUF 量化（推荐）

GGUF 是 llama.cpp 的原生格式，支持多种量化级别，部署最灵活。

# 步骤1：转换为 GGUF F16
python convert_hf_to_gguf.py \
    meta-llama/Meta-Llama-3.1-8B-Instruct \
    --outfile llama3.1-8b-f16.gguf \
    --outtype f16

# 步骤2：量化到不同精度
./llama-quantize llama3.1-8b-f16.gguf llama3.1-8b-q2k.gguf Q2_K
./llama-quantize llama3.1-8b-f16.gguf llama3.1-8b-q4km.gguf Q4_K_M
./llama-quantize llama3.1-8b-f16.gguf llama3.1-8b-q5km.gguf Q5_K_M
./llama-quantize llama3.1-8b-f16.gguf llama3.1-8b-q8_0.gguf Q8_0

7.4 量化方法对比

特性	GPTQ	AWQ	GGUF
量化精度	INT4/INT8	INT4	INT2-INT8
推理速度	快（GPU）	最快（GPU）	中等
CPU 支持	否	否	是
量化速度	慢	中等	快
质量保持	好	最好	好
生态兼容	Transformers	vLLM	llama.cpp
推荐场景	GPU 推理	生产部署	灵活部署

---

8. LoRA/QLoRA 微调实战

8.1 环境准备

# 安装依赖
pip install torch transformers datasets accelerate peft bitsandbytes trl
pip install wandb  # 可选，用于训练监控

8.2 数据准备

from datasets import Dataset

# 构建指令微调数据集
train_data = {
    "instruction": [
        "请总结以下文本的核心观点",
        "将以下英文翻译成中文",
        "解释什么是递归",
    ],
    "input": [
        "人工智能正在改变各个行业...",
        "Machine learning is a subset of AI.",
        "",
    ],
    "output": [
        "核心观点：人工智能技术正在各行业引发变革...",
        "机器学习是人工智能的一个子集。",
        "递归是一种编程技术，指函数直接或间接调用自身...",
    ]
}

dataset = Dataset.from_dict(train_data)

# 格式化为对话格式
def format_prompt(example):
    if example["input"]:
        text = f"""<|begin_of_text|><|start_header_id|>user<|end_header_id|>

{example["instruction"]}

{example["input"]}<|eot_id|><|start_header_id|>assistant<|end_header_id|>

{example["output"]}<|eot_id|>"""
    else:
        text = f"""<|begin_of_text|><|start_header_id|>user<|end_header_id|>

{example["instruction"]}<|eot_id|><|start_header_id|>assistant<|end_header_id|>

{example["output"]}<|eot_id|>"""
    return {"text": text}

dataset = dataset.map(format_prompt)

8.3 QLoRA 微调

import torch
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    BitsAndBytesConfig,
    TrainingArguments,
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from trl import SFTTrainer

model_id = "meta-llama/Meta-Llama-3.1-8B-Instruct"

# 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_id,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True,
)

tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "right"

# 准备模型进行 QLoRA 训练
model = prepare_model_for_kbit_training(model)

# LoRA 配置
lora_config = LoraConfig(
    r=16,                    # LoRA 秩
    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",
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出示例: trainable params: 41,943,040 || all params: 8,072,204,288 || trainable%: 0.5196

# 训练参数
training_args = TrainingArguments(
    output_dir="./llama3-8b-qlora",
    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_strategy="epoch",
    fp16=False,
    bf16=True,
    optim="paged_adamw_8bit",
    gradient_checkpointing=True,
    gradient_checkpointing_kwargs={"use_reentrant": False},
    report_to="none",  # 改为 "wandb" 以启用 W&B
)

# 开始训练
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    dataset_text_field="text",
    max_seq_length=2048,
    tokenizer=tokenizer,
    packing=True,
)

trainer.train()

# 保存 LoRA 适配器
trainer.save_model("./llama3-8b-qlora-final")

8.4 合并与部署

from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载基础模型和 LoRA 适配器
base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Meta-Llama-3.1-8B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
model = PeftModel.from_pretrained(base_model, "./llama3-8b-qlora-final")

# 合并 LoRA 权重到基础模型
merged_model = model.merge_and_unload()
merged_model.save_pretrained("./llama3-8b-merged")
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3.1-8B-Instruct")
tokenizer.save_pretrained("./llama3-8b-merged")

# 转换为 GGUF 用于 llama.cpp 部署
# python convert_hf_to_gguf.py ./llama3-8b-merged --outfile llama3-8b-merged.gguf --outtype f16

---

9. RAG 本地知识库构建

9.1 架构设计

RAG（Retrieval-Augmented Generation）通过检索外部知识来增强模型的回答能力。

用户提问
    ↓
[向量检索] ← 文档向量库 (ChromaDB/FAISS)
    ↓
相关文档片段
    ↓
[Llama 3 生成] ← 原始问题 + 检索结果
    ↓
最终回答

9.2 完整实现

from langchain_community.document_loaders import DirectoryLoader, TextLoader
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_community.vectorstores import Chroma
from langchain_community.llms import Ollama
from langchain.chains import RetrievalQA

# 1. 加载文档
loader = DirectoryLoader(
    "./knowledge_base",
    glob="**/*.md",
    loader_cls=TextLoader,
    loader_kwargs={"encoding": "utf-8"}
)
documents = loader.load()
print(f"加载了 {len(documents)} 个文档")

# 2. 文本分割
text_splitter = RecursiveCharacterTextSplitter(
    chunk_size=500,
    chunk_overlap=50,
    separators=["\n\n", "\n", "。", "！", "？", ".", " "]
)
chunks = text_splitter.split_documents(documents)
print(f"分割为 {len(chunks)} 个片段")

# 3. 创建向量数据库
embeddings = HuggingFaceEmbeddings(
    model_name="BAAI/bge-small-zh-v1.5",
    model_kwargs={"device": "cuda"},
    encode_kwargs={"normalize_embeddings": True}
)

vectorstore = Chroma.from_documents(
    documents=chunks,
    embedding=embeddings,
    persist_directory="./chroma_db"
)

# 4. 创建检索器
retriever = vectorstore.as_retriever(
    search_type="similarity",
    search_kwargs={"k": 3}
)

# 5. 构建 RAG 链
llm = Ollama(model="llama3", temperature=0.3)

qa_chain = RetrievalQA.from_chain_type(
    llm=llm,
    chain_type="stuff",
    retriever=retriever,
    return_source_documents=True,
)

# 6. 查询
result = qa_chain.invoke({"query": "公司的请假制度是什么？"})
print("回答:", result["result"])
print("\n参考来源:")
for doc in result["source_documents"]:
    print(f"  - {doc.metadata['source']}: {doc.page_content[:100]}...")

9.3 高级 RAG 优化

# 混合检索：向量检索 + BM25 关键词检索
from langchain.retrievers import EnsembleRetriever
from langchain_community.retrievers import BM25Retriever

bm25_retriever = BM25Retriever.from_documents(chunks)
bm25_retriever.k = 3

vector_retriever = vectorstore.as_retriever(search_kwargs={"k": 3})

# 混合检索，权重可调
ensemble_retriever = EnsembleRetriever(
    retrievers=[bm25_retriever, vector_retriever],
    weights=[0.4, 0.6]
)

# 重排序：使用交叉编码器对检索结果重新排序
from langchain.retrievers import ContextualCompressionRetriever
from langchain_community.cross_encoders import HuggingFaceCrossEncoder
from langchain.retrievers.document_compressors import CrossEncoderReranker

cross_encoder = HuggingFaceCrossEncoder(model_name="BAAI/bge-reranker-base")
reranker = CrossEncoderReranker(model=cross_encoder, top_n=3)

compression_retriever = ContextualCompressionRetriever(
    base_compressor=reranker,
    base_retriever=ensemble_retriever
)

---

10. Agent 应用开发

10.1 函数调用（Function Calling）

Llama 3.1+ 支持原生工具调用能力：

import json
from openai import OpenAI

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

# 定义工具
tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "获取指定城市的天气信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "城市名称"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
                },
                "required": ["city"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "搜索互联网获取最新信息",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {"type": "string", "description": "搜索关键词"}
                },
                "required": ["query"]
            }
        }
    }
]

# 工具实现
def get_weather(city, unit="celsius"):
    return {"city": city, "temp": 22, "unit": unit, "condition": "晴"}

def search_web(query):
    return {"results": [f"搜索结果: {query}相关内容"]}

# Agent 循环
def agent_loop(user_message, max_iterations=5):
    messages = [{"role": "user", "content": user_message}]
    
    for i in range(max_iterations):
        response = client.chat.completions.create(
            model="llama3.1",
            messages=messages,
            tools=tools,
            tool_choice="auto"
        )
        
        assistant_msg = response.choices[0].message
        messages.append(assistant_msg)
        
        # 如果没有工具调用，返回最终回答
        if not assistant_msg.tool_calls:
            return assistant_msg.content
        
        # 处理工具调用
        for tool_call in assistant_msg.tool_calls:
            func_name = tool_call.function.name
            func_args = json.loads(tool_call.function.arguments)
            
            if func_name == "get_weather":
                result = get_weather(**func_args)
            elif func_name == "search_web":
                result = search_web(**func_args)
            else:
                result = {"error": f"未知工具: {func_name}"}
            
            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result, ensure_ascii=False)
            })
    
    return "达到最大迭代次数"

# 使用
answer = agent_loop("今天北京天气怎么样？")
print(answer)

10.2 LangChain Agent

from langchain_community.llms import Ollama
from langchain.agents import AgentExecutor, create_react_agent
from langchain.tools import Tool
from langchain import hub

llm = Ollama(model="llama3.1", temperature=0)

# 定义工具
def calculator(expression):
    try:
        return str(eval(expression))
    except:
        return "计算错误"

tools = [
    Tool(name="Calculator", func=calculator, description="数学计算工具"),
    Tool(name="Search", func=lambda q: f"搜索结果: {q}", description="搜索工具"),
]

# 创建 ReAct Agent
prompt = hub.pull("hwchase17/react")
agent = create_react_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True, handle_parsing_errors=True)

result = agent_executor.invoke({"input": "计算 (15 * 23) + 47 等于多少？"})
print(result["output"])

---

11. 性能优化策略

11.1 推理加速

# vLLM 连续批处理（高吞吐场景）
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-8B-Instruct \
    --max-num-seqs 64 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.95 \
    --enable-chunked-prefill

# llama.cpp 批量推理
./llama-cli -m model.gguf -f prompts.txt -c 2048 -t 8 -ngl 99 --batch-size 512

11.2 KV Cache 优化

# vLLM 使用量化 KV Cache 节省显存
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-8B-Instruct \
    --kv-cache-dtype fp8 \
    --max-model-len 16384

11.3 推理参数调优

参数	低值效果	高值效果	推荐值
temperature	确定性强	创造性强	0.1-0.7
top_p	保守	多样	0.9-0.95
top_k	保守	多样	40-50
repeat_penalty	无惩罚	强惩罚	1.05-1.15
max_tokens	短回答	长回答	按需设置

11.4 基准测试

# llama.cpp 性能测试
./llama-bench -m ./models/llama3.1-8b-q4km.gguf -t 8 -ngl 99

# 输出示例:
# model                          size    threads  batch  prompt  eval
# llama3.1-8b-q4km.gguf        5.0GB    8        512    128     32
# pp (prompt processing):  2845.32 tokens/s
# tg (token generation):    87.45 tokens/s

---

12. 与 Qwen/DeepSeek 对比

12.1 模型对比表

维度	Llama 3.1 8B	Qwen2.5 7B	DeepSeek-V2-Lite
参数量	8B	7B	16B (MoE)
激活参数	8B	7B	2.4B
上下文	128K	128K	32K
中文能力	★★★★	★★★★★	★★★★★
英文能力	★★★★★	★★★★	★★★★
代码能力	★★★★	★★★★	★★★★★
数学推理	★★★★	★★★★	★★★★★
Agent 能力	★★★★	★★★★	★★★★
社区生态	★★★★★	★★★★	★★★☆
多模态	有 (11B Vision)	有 (Qwen-VL)	有 (DeepSeek-VL)

12.2 选型建议

选择 Llama 3 的场景：

• 英文为主的应用
• 需要最丰富的社区生态和第三方工具支持
• 多语言应用（128K 词表优势）
• 学术研究（Meta 论文详尽）

选择 Qwen 2.5 的场景：

• 中文为核心的应用
• 需要更强的中文理解和生成能力
• 国内部署，社区支持好
• 阿里云生态集成

选择 DeepSeek 的场景：

• 代码生成和理解
• 数学和逻辑推理
• 追求推理效率（MoE 架构激活参数少）
• 预算有限但需要高性能

12.3 混合部署策略

# 路由策略：根据任务类型选择模型
def route_to_model(task_type, content):
    if task_type == "code":
        return "deepseek-v2"  # 代码任务用 DeepSeek
    elif task_type == "chinese":
        return "qwen2.5"      # 中文任务用 Qwen
    elif task_type == "general":
        return "llama3.1"      # 通用任务用 Llama
    else:
        return "llama3.1"      # 默认

---

13. 常见问题与排错

13.1 显存不足 (OOM)

# 问题：CUDA out of memory
# 解决方案：

# 1. 使用更小的量化
ollama pull llama3:7b-q4_0  # 而非 q8_0

# 2. 减少上下文长度
--max-model-len 2048

# 3. 降低 GPU 内存占用
--gpu-memory-utilization 0.85

# 4. 使用 CPU offload
-ngl 20  # 只将 20 层放 GPU，其余在 CPU

13.2 模型加载慢

# 使用 safetensors 格式（更快的加载）
# HuggingFace 模型通常默认支持

# 预加载模型（Ollama）
OLLAMA_KEEP_ALIVE=24h ollama serve

# mmap 加速（llama.cpp）
./llama-cli -m model.gguf --mlock  # 锁定内存，避免换页

13.3 中文输出质量差

# 确保使用正确的提示模板
prompt = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>

你是一个专业的中文AI助手。请始终使用中文回答。<|eot_id|><|start_header_id|>user<|end_header_id|>

{user_input}<|eot_id|><|start_header_id|>assistant<|end_header_id|>
"""

13.4 多 GPU 部署

# vLLM 张量并行
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-70B-Instruct \
    --tensor-parallel-size 4

# llama.cpp 多 GPU
CUDA_VISIBLE_DEVICES=0,1,2,3 ./llama-cli -m model.gguf -ngl 99

---

14. 总结与资源

14.1 部署方案选择指南

你的需求是什么？
    │
    ├── 快速体验 → Ollama + Open WebUI
    │
    ├── 生产部署 → vLLM + 量化模型
    │
    ├── 灵活部署 → llama.cpp + GGUF
    │
    ├── 微调训练 → QLoRA + PEFT
    │
    └── RAG 应用 → LangChain + 向量数据库

14.2 关键资源

• 官方仓库：https://github.com/meta-llama/llama3
• Ollama：https://ollama.ai
• vLLM：https://github.com/vllm-project/vllm
• llama.cpp：https://github.com/ggerganov/llama.cpp
• Open WebUI：https://github.com/open-webui/open-webui
• HuggingFace 模型库：https://huggingface.co/meta-llama
• GGUF 模型下载：https://huggingface.co/models?search=llama+gguf

14.3 学习路径建议

1. 入门：安装 Ollama → 运行 Llama 3 8B → 使用 Open WebUI
2. 进阶：学习量化 → 用 llama.cpp 部署 → 性能调优
3. 实战：构建 RAG 知识库 → 开发 Agent 应用
4. 深入：QLoRA 微调 → 自定义数据训练 → 模型评估

---

本教程最后更新于 2025 年 5 月。大模型领域发展迅速，建议关注各项目官方仓库获取最新信息。