1. 项目概述：为什么要在本地部署并训练DeepSeek？

最近和几个做AI应用开发的朋友聊天，发现一个挺有意思的现象：大家一边在讨论哪个云端大模型API又降价了，一边又悄悄地在自己的机器上折腾本地部署。这听起来有点矛盾，但仔细一想，逻辑其实很清晰。云端API确实方便，开箱即用，按需付费，但对于需要处理敏感数据、追求极致响应速度、或者想深度定制模型行为的场景来说，本地部署就成了刚需。特别是当你手头有一批高质量的行业数据，想训练一个专属的“行业专家”时，把数据上传到云端总让人心里不踏实，成本也难以控制。

DeepSeek作为当前开源大模型中的佼佼者，其优秀的代码能力和推理性能吸引了大量开发者。这个项目，就是要把DeepSeek“请”到我们自己的电脑或服务器上，并教会它学习我们独有的知识。想象一下，你有一个法律条文数据库、一份内部技术文档库，或者一堆未公开的创意文案，通过本地训练，你可以得到一个精通这些领域、且完全受你控制的AI助手。这不仅仅是技术上的“玩具”，更是能直接产生业务价值的生产力工具。

整个过程可以拆解为三个核心阶段： 环境准备与模型部署 、 数据准备与预处理 、 模型训练与微调 。每个阶段都有不少细节和“坑”，我会结合自己的实操经验，把每一步都讲透，让你不仅能跟着做出来，更能理解背后的“为什么”。

2. 核心思路与方案选型：为什么是这套组合拳？

在动手之前，我们先来盘一盘家底，明确目标和路径。本地部署和训练一个大语言模型，听起来高大上，但本质上就是解决三个问题： 用什么工具跑起来？拿什么数据喂给它？怎么让它学会新东西？

2.1 部署工具选型：Ollama vs. 原生推理框架

目前最流行的本地大模型部署方案主要有两条路：一是使用Ollama、LM Studio这类一体化工具，二是直接使用模型原生的推理框架（如vLLM、Transformers）。

• Ollama/LM Studio（推荐新手和快速原型） ：这类工具把模型加载、对话交互、甚至简单的API服务都打包好了，提供图形界面或简单的命令行操作。你只需要下载模型文件，几条命令就能跑起来一个聊天机器人。它的优势是 开箱即用，生态友好 ，社区提供了大量预量化好的模型，直接 ollama run deepseek-coder 就能对话。对于快速验证模型能力、进行轻量级测试来说，它是首选。
• 原生推理框架（推荐深度定制和训练） ：如果你计划进行模型训练或微调，那么直接使用PyTorch + Transformers库，或者更高效的推理服务器vLLM，是更专业的选择。这套方案 灵活性极高 ，你可以完全控制模型的加载方式、推理参数，更重要的是，它是进行 参数高效微调（PEFT） 如LoRA、QLoRA的基础。我们后续的训练步骤，将主要基于这个方案。

我的选择与理由 ：本次教程，我会采用 “Ollama用于初步验证和体验，Transformers/PEFT用于后续训练” 的混合策略。先用Ollama快速把模型跑起来，确保硬件兼容性，感受模型的基础能力。然后，再切换到Transformers环境，进行严肃的数据准备和训练工作。这样既能降低入门门槛，又能保证训练环节的专业性和可扩展性。

2.2 训练方法选型：全参数微调 vs. 参数高效微调

这是训练环节最关键的选择。假设我们有一个7B参数的DeepSeek模型。

• 全参数微调 ：意味着更新模型所有的70亿个参数。这需要巨大的显存（通常需要模型参数4倍以上的显存，即280GB以上），几乎只能在多张顶级A100/H100显卡上完成，成本极高。
• 参数高效微调 ：以 LoRA 为代表，它不在原始模型庞大的参数矩阵上直接更新，而是为其中一些关键层（如注意力层的QKV矩阵）旁路添加一对小的、可训练的“低秩适配器”矩阵。训练时，只更新这些只占原模型参数0.1%-1%的小矩阵，原始大模型参数被冻结。训练完成后，可以将这些小矩阵合并回原模型，得到一个独立的新模型文件。

两者的对比如下：

特性	全参数微调	LoRA等PEFT方法
显存需求	极高 (模型参数4倍+)	极低 (通常<10GB)
计算需求	极高	较低
硬件门槛	多卡高端服务器	单张消费级显卡(如RTX 3090/4090)
输出结果	一个完整的新模型文件	一个很小的适配器文件(.bin, ~几十MB)
灵活性	模型被彻底改变	可轻松切换不同任务的适配器
适合场景	数据量极大，任务差异大	数据量有限，任务特定，个人或小团队

结论显而易见 ：对于绝大多数个人开发者、中小团队和垂直场景应用， LoRA是目前性价比最高、最可行的训练方案 。我们本次教程也将以LoRA为核心训练方法。

2.3 数据格式与任务定义

大模型训练不是简单地把文本丢进去。你需要根据目标，将数据构造成模型能理解的“监督微调”格式。常见格式如下：

• 指令-输出对 ：最常用。 {"instruction": "将以下文本翻译成英文：...", "input": "", "output": "..."}
• 多轮对话 ：模拟真实对话。 {"conversations": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]}
• 纯补全 ：让模型续写。 {"text": "故事开头是...接下来"} 期望模型生成后续。

你需要想清楚：我要训练模型做什么？是做一个专业的客服机器人、一个代码补全助手，还是一个创意写作工具？根据目标，去收集和构造相应格式的数据。

3. 环境准备与模型部署：从零到一的启动

理论清楚了，我们开始动手。第一步是把环境搭好，并把基础的DeepSeek模型成功运行起来。

3.1 硬件与基础软件检查

• 显卡 ：这是最重要的。你需要一块至少8GB显存的NVIDIA显卡（如RTX 3060 12G, RTX 4070 12G, RTX 3090/4090 24G）。显存越大，能跑的模型越大，批量训练数据也越多。使用 nvidia-smi 命令可以查看显卡信息。
• 内存 ：建议16GB以上。模型加载和数据处理都会占用大量内存。
• 硬盘 ：预留至少50GB的固态硬盘空间，用于存放模型文件（一个7B模型约14GB）和数据集。
• Python ：确保安装Python 3.8-3.11版本。推荐使用Anaconda或Miniconda来创建独立的虚拟环境，避免包冲突。
• CUDA ：根据你的显卡型号，安装对应版本的CUDA Toolkit（如11.8, 12.1）。这是PyTorch等框架调用GPU的基础。

3.2 使用Ollama快速部署（验证阶段）

这是最快体验模型的方式。

1. 安装Ollama ：前往Ollama官网，根据你的操作系统（Windows/macOS/Linux）下载并安装。
2. 拉取DeepSeek模型 ：打开终端（或命令行），运行以下命令。Ollama会自动下载预量化好的模型。

   # 拉取DeepSeek-Coder模型（代码能力突出）
   ollama pull deepseek-coder:6.7b
   # 或者拉取通用的DeepSeek-V2模型
   # ollama pull deepseek-v2:16b
   

   模型名称后的 :6.7b 指定了参数量和版本，你可以去Ollama官网模型库查找其他可用的DeepSeek变体。
3. 运行与对话 ：模型拉取成功后，直接运行：

   ollama run deepseek-coder:6.7b
   

   之后就可以在命令行里和AI对话了，可以问它代码问题，测试其基础能力。
4. 启动API服务 ：Ollama还内置了OpenAI兼容的API服务，方便其他程序调用。

   ollama serve
   

   默认会在 11434 端口启动服务。你可以用curl或Postman测试：

   curl http://localhost:11434/api/generate -d '{
     "model": "deepseek-coder:6.7b",
     "prompt": "用Python写一个快速排序函数",
     "stream": false
   }'
   

实操心得 ：Ollama下载的模型文件通常存放在 ~/.ollama/models （Linux/macOS）或 C:\Users\<用户名>\.ollama\models （Windows）目录下。第一次拉取模型可能会比较慢，取决于网络。用Ollama跑通，是建立信心的关键一步，它能帮你排除掉最基础的硬件驱动和环境问题。

3.3 构建PyTorch与Transformers训练环境（核心阶段）

为了后续训练，我们需要一个更可控的Python环境。

1. 创建虚拟环境 ：

   conda create -n deepseek_train python=3.10
   conda activate deepseek_train
   

2. 安装PyTorch ：前往PyTorch官网，根据你的CUDA版本，生成对应的安装命令。例如，CUDA 11.8：

   pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
   

3. 安装核心库 ：

   pip install transformers datasets accelerate peft bitsandbytes trl
   

   • transformers : Hugging Face核心库，用于加载模型和分词器。
   • datasets : 处理数据集的利器。
   • accelerate : Hugging Face的分布式训练库，简化多卡/混合精度训练。
   • peft : 实现LoRA等参数高效微调方法的库。
   • bitsandbytes : 实现4-bit/8-bit量化，极大降低显存消耗。
   • trl : 提供SFTTrainer等更方便的训练循环。

4. 验证安装 ：在Python交互环境中执行以下命令，确保关键库已就位且能识别GPU。

   import torch, transformers, peft
   print(torch.__version__)
   print(torch.cuda.is_available()) # 应返回True
   print(transformers.__version__)
   

4. 数据准备与预处理：喂给AI的“饲料”如何制作？

数据是训练的灵魂。垃圾进，垃圾出。这一步直接决定了最终模型的质量。

4.1 数据收集与来源

你的数据从哪里来？

• 内部文档 ：Markdown、PDF、Word、Confluence页面。需要转换成纯文本。
• 公开数据集 ：Hugging Face Datasets Hub上有海量数据集，如 alpaca （指令数据）、 code_alpaca （代码指令）、 dolly 等。可以直接用 datasets 库加载。
• 人工构造 ：对于非常垂直的领域，可能需要自己编写一批高质量的指令-输出对。这是最耗时但往往最有效的方法。
• 网络爬取 ：注意版权和合规性。可以使用 scrapy 、 selenium 等工具，但务必清洗和去重。

4.2 数据清洗与格式化

原始数据通常很“脏”，必须清洗。

1. 去重 ：完全相同的样本毫无意义，用哈希或直接比对去除。
2. 过滤 ：
   • 去除过短（如字符数<10）或过长（如字符数>5000）的文本。
   • 去除包含大量乱码、特殊字符、无关链接的文本。
   • 对于指令数据，过滤掉指令不清晰或输出质量极差的样本。
3. 格式化 ：将清洗后的数据，统一转换成之前提到的JSON格式。例如，一个指令数据集可能长这样：

   [
     {
       "instruction": "解释什么是牛顿第一定律。",
       "input": "",
       "output": "牛顿第一定律，也称为惯性定律，指出：任何物体都要保持匀速直线运动或静止状态，直到外力迫使它改变运动状态为止。"
     },
     {
       "instruction": "将下面的句子翻译成法语。",
       "input": "Hello, how are you?",
       "output": "Bonjour, comment allez-vous ?"
     }
   ]
   

4. 划分数据集 ：将数据按比例划分，例如 90% 用于训练，5% 用于验证，5% 用于测试。验证集用于在训练中监控模型表现，防止过拟合；测试集用于最终评估。

4.3 使用代码进行数据预处理实战

假设我们有一个收集好的 raw_data.jsonl 文件（每行一个JSON对象）。下面是一个完整的预处理脚本示例：

import json
from datasets import Dataset, DatasetDict
import re

def clean_text(text):
    """清洗文本的简单函数"""
    if not text:
        return ""
    # 移除多余的空格和换行
    text = re.sub(r'\s+', ' ', text).strip()
    # 这里可以添加更多清洗规则，如移除特定符号、修复编码等
    return text

def load_and_process_data(file_path):
    samples = []
    with open(file_path, 'r', encoding='utf-8') as f:
        for line in f:
            item = json.loads(line)
            # 假设原始数据有'question'和'answer'字段，我们要转换成instruction格式
            instruction = clean_text(item.get('question', ''))
            output = clean_text(item.get('answer', ''))
            
            # 过滤掉无效数据
            if len(instruction) < 5 or len(output) < 10:
                continue
                
            samples.append({
                "instruction": instruction,
                "input": "", # 本例中没有额外输入
                "output": output
            })
    
    # 转换为Hugging Face Dataset格式
    dataset = Dataset.from_list(samples)
    
    # 划分数据集
    split_dataset = dataset.train_test_split(test_size=0.1, seed=42) # 90%训练，10%临时
    # 再从临时测试集中分一半作为验证集
    test_valid = split_dataset['test'].train_test_split(test_size=0.5, seed=42)
    
    # 最终得到 train, validation, test
    final_dataset = DatasetDict({
        'train': split_dataset['train'],
        'validation': test_valid['train'], # 注意这里，第一次split的test又被split了
        'test': test_valid['test']
    })
    
    return final_dataset

# 使用函数
processed_data = load_and_process_data('raw_data.jsonl')
print(processed_data)
# 保存处理好的数据集
processed_data.save_to_disk('./my_finetune_dataset')

注意事项 ：数据预处理没有银弹。你需要根据自己数据的实际情况反复调整清洗规则。一个重要的原则是： 宁可少而精，不要多而杂 。几千条高质量的数据，远胜于几十万条充满噪声的数据。在划分数据集时，务必确保训练集、验证集、测试集的数据分布是相似的，否则评估结果会失真。

5. 模型训练与微调实战：让AI学会你的“独家秘籍”

环境好了，数据齐了，现在进入最核心的训练环节。我们将使用QLoRA（量化版的LoRA）技术，在消费级显卡上微调DeepSeek模型。

5.1 加载模型与分词器

我们以 deepseek-ai/deepseek-coder-6.7b-instruct 这个模型为例。它已经针对指令遵循进行了初步训练，是很好的基座模型。

from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
import torch

# 定义模型名称
model_name = "deepseek-ai/deepseek-coder-6.7b-instruct"

# 配置4-bit量化，极大节省显存
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True, # 使用4-bit量化加载模型
    bnb_4bit_quant_type="nf4", # 量化数据类型
    bnb_4bit_compute_dtype=torch.float16, # 计算时使用float16
    bnb_4bit_use_double_quant=True # 双重量化，进一步压缩
)

# 加载分词器
tokenizer = AutoTokenizer.from_pretrained(model_name)
# 设置padding token（如果模型没有）
if tokenizer.pad_token is None:
    tokenizer.pad_token = tokenizer.eos_token

# 加载模型，应用量化配置
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config, # 传入量化配置
    device_map="auto", # 自动将模型层分配到可用的GPU/CPU上
    trust_remote_code=True # 信任来自Hugging Face的代码
)

5.2 配置LoRA参数

接下来，我们告诉 peft 库，要对模型的哪些部分应用LoRA适配器。

from peft import LoraConfig, get_peft_model, TaskType

# 定义LoRA配置
lora_config = LoraConfig(
    task_type=TaskType.CAUSAL_LM, # 因果语言模型任务
    r=8, # LoRA秩（rank），适配器矩阵的维度。值越小，参数量越少，但能力可能越弱。通常8-32之间。
    lora_alpha=32, # 缩放参数，通常设置为r的2-4倍。
    lora_dropout=0.1, # LoRA层的dropout率，防止过拟合。
    target_modules=["q_proj", "v_proj"], # 将LoRA适配器应用到注意力层的query和value投影矩阵上。
    # 对于不同模型，target_modules可能不同。对于LLaMA/DeepSeek架构，通常是"q_proj","v_proj","k_proj","o_proj"。
    bias="none" # 不训练偏置项。
)

# 将LoRA适配器应用到原模型上
model = get_peft_model(model, lora_config)
# 打印可训练参数数量
model.print_trainable_parameters()
# 你会看到类似输出：trainable params: 4,194,304 || all params: 6,742,609,920 || trainable%: 0.0622%
# 只有0.06%的参数需要训练！这就是LoRA的魔力。

5.3 数据编码与格式化

模型看不懂原始文本，需要分词器将其转换成数字ID（Token）。

def format_instruction(example):
    """将一条数据格式化成模型训练时接受的文本格式"""
    # 根据你的数据格式调整
    if example['input']:
        text = f"### Instruction:\n{example['instruction']}\n\n### Input:\n{example['input']}\n\n### Response:\n"
    else:
        text = f"### Instruction:\n{example['instruction']}\n\n### Response:\n"
    # 注意：这里只生成输入部分（指令+问题），输出部分（回答）会在计算损失时用到。
    return {"text": text}

def tokenize_function(examples):
    """分词函数"""
    # 先格式化
    formatted_examples = [format_instruction(e)['text'] for e in examples]
    # 对输入（指令部分）进行分词
    model_inputs = tokenizer(formatted_examples, max_length=512, truncation=True, padding="max_length")
    
    # 对输出（回答部分）进行分词，并计算labels
    # 在因果语言模型中，labels通常就是输入+输出的token ids，并且我们将输入部分的loss忽略掉。
    responses = [e['output'] for e in examples]
    # 将回答也分词
    with tokenizer.as_target_tokenizer():
        response_ids = tokenizer(responses, max_length=256, truncation=True, padding="max_length")
    
    # 将回答的token ids拼接到输入后面，形成完整的上下文
    # 但更常见的做法是：将“指令+回答”作为一个整体进行分词，然后通过attention mask将指令部分的loss屏蔽。
    # 这里采用另一种清晰的方法：直接为labels赋值。
    labels = []
    for i in range(len(examples)):
        # 获取输入和输出的token ids
        input_ids = model_inputs['input_ids'][i]
        response_id = response_ids['input_ids'][i]
        # 将输入部分的label设置为-100（在计算loss时被忽略）
        input_len = len([id for id in input_ids if id != tokenizer.pad_token_id])
        # 将输出部分的label设置为response_id
        # 我们需要构造一个和input_ids一样长的labels序列
        label = [-100] * len(input_ids) # 先全部填充为-100
        # 假设我们把回答放在最后，将回答部分的label替换为真实的token id
        # 这是一个简化逻辑，实际中需要更精细地控制位置。
        # 更稳健的做法是使用trl库的SFTTrainer，它会自动处理。
        pass # 此处简化，实际训练推荐使用SFTTrainer
    
    model_inputs["labels"] = labels
    return model_inputs

# 应用分词函数到数据集
tokenized_datasets = processed_data.map(tokenize_function, batched=True, remove_columns=processed_data["train"].column_names)

由于手动处理labels比较繁琐且容易出错， 强烈推荐使用 trl 库的 SFTTrainer ，它封装了这些细节。

5.4 使用SFTTrainer进行训练

from trl import SFTTrainer, DataCollatorForCompletionOnlyLM
from transformers import TrainingArguments

# 重新定义更简单的格式化函数，SFTTrainer需要它
def formatting_prompts_func(example):
    output_texts = []
    for i in range(len(example['instruction'])):
        instr = example['instruction'][i]
        inp = example['input'][i]
        resp = example['output'][i]
        if inp:
            text = f"### Instruction:\n{instr}\n\n### Input:\n{inp}\n\n### Response:\n{resp}"
        else:
            text = f"### Instruction:\n{instr}\n\n### Response:\n{resp}"
        output_texts.append(text)
    return output_texts

# 配置训练参数
training_args = TrainingArguments(
    output_dir="./deepseek-lora-finetuned", # 输出目录
    num_train_epochs=3, # 训练轮数
    per_device_train_batch_size=4, # 每个GPU的批次大小，根据显存调整
    per_device_eval_batch_size=4,
    gradient_accumulation_steps=4, # 梯度累积步数，模拟更大的批次
    warmup_steps=100, # 学习率预热步数
    logging_steps=10, # 每10步打印一次日志
    save_steps=200, # 每200步保存一次检查点
    eval_steps=200, # 每200步在验证集上评估一次
    evaluation_strategy="steps",
    learning_rate=2e-4, # 学习率，LoRA通常可以设大一点
    fp16=True, # 使用混合精度训练，节省显存加速训练
    optim="paged_adamw_8bit", # 使用分页的8-bit AdamW优化器，进一步省显存
    report_to="none", # 不报告给wandb等平台，本地训练
    save_total_limit=3, # 只保留最新的3个检查点
    load_best_model_at_end=True, # 训练结束后加载验证集上最好的模型
)

# 初始化SFTTrainer
trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=processed_data["train"],
    eval_dataset=processed_data["validation"],
    formatting_func=formatting_prompts_func, # 传入格式化函数
    max_seq_length=1024, # 序列最大长度
    tokenizer=tokenizer,
    dataset_text_field="text", # 我们的格式化函数返回的就是'text'字段
)

# 开始训练！
trainer.train()

# 保存训练好的LoRA适配器
trainer.model.save_pretrained("./my_lora_adapter")
# 也可以将适配器与基础模型合并，得到一个完整的模型文件（可选）
# merged_model = model.merge_and_unload()
# merged_model.save_pretrained("./merged_model")
tokenizer.save_pretrained("./my_lora_adapter")

5.5 关键参数解析与调优经验

• per_device_train_batch_size ：这是最大的显存杀手。从1开始尝试，如果出现OOM（内存不足），就减小它，或者增大 gradient_accumulation_steps 。 真实批次大小 = per_device_train_batch_size * gradient_accumulation_steps * GPU数量 。
• learning_rate ：对于LoRA，学习率通常可以设置得比全参数微调大一些（例如1e-4到5e-4）。2e-4是一个不错的起点。
• num_train_epochs ：取决于数据量。数据量少（几千条）可以训练5-10轮；数据量多（几万条）训练3-5轮可能就够了。 一定要看验证集损失 ，如果验证集损失开始上升，说明过拟合了，应该早停。
• max_seq_length ：决定了模型能处理多长的文本。越长消耗显存越多。根据你的数据长度合理设置，比如512或1024。

实操心得 ：训练开始后，务必监控GPU显存使用情况（ nvidia-smi -l 1 ）和训练日志。如果显存一直很高但没爆，说明设置合理。如果训练损失一直不下降，可能是学习率太小、数据质量太差或模型容量不够。 验证集损失是你最好的朋友 ，它是判断模型是否过拟合、是否需要早停的核心指标。

6. 模型测试、部署与应用：检验成果并投入使用

训练完成后，我们得到了一个LoRA适配器文件（ adapter_model.bin ）和配置文件。接下来就是检验效果，并把它用起来。

6.1 加载训练好的模型进行推理

from peft import PeftModel

# 重新加载基础模型和分词器（量化配置需与训练时一致）
base_model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",
    trust_remote_code=True
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

# 加载训练好的LoRA适配器
model = PeftModel.from_pretrained(base_model, "./my_lora_adapter")

# 切换到评估模式
model.eval()

# 准备一个测试问题
prompt = "### Instruction:\n用Python写一个函数，计算斐波那契数列的第n项。\n\n### Response:\n"

# 分词
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

# 生成
with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=256, # 生成的最大token数
        temperature=0.7, # 温度，控制随机性。越低越确定，越高越有创意。
        top_p=0.9, # 核采样参数，与temperature配合使用。
        do_sample=True,
        repetition_penalty=1.1, # 重复惩罚，避免重复生成。
    )

# 解码并打印
generated_text = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(generated_text)

6.2 与原始模型对比测试

这是最关键的一步。你需要准备一个 测试集 （之前划分好的，模型从未见过的数据），分别用原始基座模型和微调后的模型进行推理，对比它们的输出。

• 定性对比 ：人工查看对于相同问题，两个模型的回答在准确性、专业性、风格上是否有明显提升。
• 定量对比 ：如果任务可评估（如翻译、摘要），可以使用BLEU、ROUGE等自动评估指标。对于开放域对话，可以设计一些评分规则，或者通过更强大的模型（如GPT-4）进行辅助评估。

6.3 部署为API服务

要让其他应用调用你的模型，需要部署成API。可以使用 FastAPI 快速搭建。

# api_server.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import List
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel
import uvicorn

app = FastAPI()

# 加载模型（全局加载一次）
# ... 此处省略加载代码，与6.1节相同 ...
# 假设 model 和 tokenizer 已加载

class ChatRequest(BaseModel):
    prompt: str
    max_tokens: int = 256
    temperature: float = 0.7

class ChatResponse(BaseModel):
    response: str

@app.post("/chat", response_model=ChatResponse)
async def chat_completion(request: ChatRequest):
    try:
        inputs = tokenizer(request.prompt, return_tensors="pt").to(model.device)
        with torch.no_grad():
            outputs = model.generate(
                **inputs,
                max_new_tokens=request.max_tokens,
                temperature=request.temperature,
                top_p=0.9,
                do_sample=True,
                repetition_penalty=1.1,
            )
        response_text = tokenizer.decode(outputs[0], skip_special_tokens=True)
        # 去除输入提示，只返回生成的响应部分（根据你的提示格式调整）
        if "### Response:" in response_text:
            response_text = response_text.split("### Response:")[-1].strip()
        return ChatResponse(response=response_text)
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

运行 python api_server.py ，你的本地AI服务就在8000端口启动了。其他应用可以通过发送HTTP POST请求到 http://localhost:8000/chat 来调用。

6.4 集成到其他应用

有了API，集成就很简单了。

• Web应用 ：用任何前端框架（React, Vue）调用这个API。
• 聊天机器人 ：接入Discord、Slack、微信机器人等。
• 代码编辑器 ：可以封装成VS Code或Cursor的插件，实现上下文感知的代码补全和解释。
• 知识库问答 ：将你的微调模型与LangChain、LlamaIndex等框架结合，构建基于私有文档的智能问答系统。

7. 常见问题、避坑指南与性能优化

在实际操作中，你几乎一定会遇到下面这些问题。这里是我踩过坑后总结的经验。

7.1 显存不足（CUDA Out Of Memory）

这是最常见的问题。

• 降低批次大小 ：首先尝试减小 per_device_train_batch_size ，比如从4降到2或1。
• 增加梯度累积 ：同步增大 gradient_accumulation_steps ，保持总的有效批次大小不变。
• 使用梯度检查点 ：在 TrainingArguments 中设置 gradient_checkpointing=True 。这会用计算时间换显存。
• 使用更低精度的量化 ：训练时使用 bnb_4bit_compute_dtype=torch.bfloat16 （如果硬件支持）或坚持float16。推理时可以考虑8-bit甚至4-bit量化加载。
• 减少序列长度 ：减小 max_seq_length ，比如从1024降到512。
• 升级硬件 ：最后的手段，换更大显存的显卡。

7.2 训练损失不下降或波动大

• 检查数据质量 ：这是最可能的原因。确保你的指令清晰，输出正确。可以随机抽样一些数据看看。
• 调整学习率 ：尝试增大或减小学习率（如5e-5, 1e-4, 2e-4）。可以开启 lr_scheduler_type （如 cosine ）。
• 检查LoRA配置 ：增大 r （如从8调到16）可能增加模型容量。尝试将LoRA应用到更多模块，如 target_modules=["q_proj","v_proj","k_proj","o_proj"] 。
• 数据量是否太少 ：如果只有几百条数据，模型很难学到泛化模式。考虑增加数据或进行数据增强。

7.3 模型输出胡言乱语或重复

• 调整生成参数 ：降低 temperature （如0.3），增加 repetition_penalty （如1.2）。
• 检查提示模板 ：确保你的推理提示模板和训练时的格式完全一致。不一致会导致模型困惑。
• 过拟合 ：如果模型在训练集上表现很好，在测试集上乱说，那就是过拟合了。需要更多数据、更早停止训练、增加Dropout或使用更小的 r 值。

7.4 训练速度太慢

• 使用Flash Attention ：如果模型和CUDA版本支持，在加载模型时设置 use_flash_attention_2=True 可以显著加速。
• 优化数据加载 ：使用 datasets 库的 .map 函数时，设置 batched=True 和 num_proc 参数（多进程处理）。
• 升级硬件 ：更快的GPU（如RTX 4090）、更快的CPU和内存、使用NVMe固态硬盘都能提升数据加载速度。

7.5 模型“遗忘”原有能力

这是微调中的一个经典问题：模型学会了新知识，但可能忘记了原有的通用能力。

• 混合数据训练 ：在你自己数据中，混入一部分高质量的通用指令数据（如alpaca数据集的一部分）。这有助于模型保持通用性。
• 使用更低的训练强度 ：减少训练轮数，使用更小的学习率，或者只训练更少的层（在 LoraConfig 中通过 target_modules 控制）。
• 评估通用能力 ：在测试时，不仅要看新任务的表现，也要用一些通用问题（如“法国的首都是哪里？”）来测试，确保能力没有严重退化。

整个流程走下来，你会发现本地部署和训练DeepSeek这样的模型，虽然步骤繁多，但每一步都有成熟的工具和社区支持，门槛已经大大降低。核心在于对数据的耐心打磨和对训练过程的细心观察与调整。别指望第一次训练就能得到完美模型，把它当成一个迭代实验的过程，根据每次的结果分析问题，持续优化数据和参数，你的专属AI助手才会越来越聪明。