本文介绍在 hugging face transformers（≥v4.51.0）中，不依赖 hub 在线下载，而是直接通过本地文件系统路径加载已下载的 deepseek-v3（或 deepseek-r1）模型完成文本生成推理的完整方法。
本文介绍在 hugging face transformers（≥v4.51.0）中，不依赖 hub 在线下载，而是直接通过本地文件系统路径加载已下载的 deepseek-v3（或 deepseek-r1）模型完成文本生成推理的完整方法。
Hugging Face 的 pipeline 接口高度灵活，支持直接传入本地模型路径——只要该路径下包含完整的、可被 Transformers 识别的模型仓库结构（如 config.json、pytorch_model.bin 或 model.safetensors、tokenizer.json、generation_config.json 等），即可无缝加载，无需移动文件至缓存目录。
✅ 正确用法示例：
假设你已将 DeepSeek-R1（DeepSeek-V3 的公开推理版本）完整克隆或下载至本地路径 /home/user/models/deepseek-r1，请确保该目录结构类似如下：
/home/user/models/deepseek-r1/ ├── config.json ├── generation_config.json ├── model.safetensors # 或 pytorch_model.bin ├── tokenizer.json ├── tokenizer_config.json ├── special_tokens_map.json └── modeling_deepseek.py # 若含自定义架构，需 trust_remote_code=True
此时，只需将绝对或相对路径传给 model 参数，并启用 trust_remote_code=True（因 DeepSeek 使用自定义模型类与 RoPE 实现）：
from transformers import pipeline
messages = [{"role": "user", "content": "Who are you?"}]
# ✅ 直接指定本地路径（支持绝对路径或相对路径）
pipe = pipeline(
"text-generation",
model="/home/user/models/deepseek-r1", # ← 替换为你的实际路径
trust_remote_code=True,
device_map="auto" # 可选：自动分配 GPU/CPU
)
outputs = pipe(messages, max_new_tokens=128)
print(outputs[0]["generated_text"][-1]["content"])
⚠️ 关键注意事项：
- 路径必须指向模型仓库根目录（即包含
config.json的那一层），而非子目录（如不要写成/.../deepseek-r1/model.safetensors）； - 若模型含自定义模块（如
modeling_deepseek.py），trust_remote_code=True为必需项，否则会报ImportError或ValueError: Unrecognized model； - 不需要手动调用
AutoTokenizer.from_pretrained()或AutoModelForCausalLM.from_pretrained()——pipeline内部已自动处理； - 若遇到
OSError: Can't load tokenizer，请检查tokenizer.json或tokenizer_config.json是否存在且格式正确； - 推荐使用
safetensors格式以提升加载安全性与速度（DeepSeek 官方仓库默认提供）。
? 进阶提示：
若需进一步控制推理行为（如量化、批处理、流式生成），可先手动构建组件：
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch
model_path = "/home/user/models/deepseek-r1"
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModelForCausalLM.from_pretrained(
model_path,
trust_remote_code=True,
torch_dtype=torch.bfloat16,
device_map="auto"
)
inputs = tokenizer.apply_chat_template(
messages, return_tensors="pt", add_generation_prompt=True
).to(model.device)
outputs = model.generate(inputs, max_new_tokens=128, do_sample=True)
print(tokenizer.decode(outputs[0], skip_special_tokens=True))
总之，本地路径加载是离线部署、隐私敏感场景及 CI/CD 流程中的推荐实践——简洁、可靠，且完全复用 Hugging Face 生态的标准接口。
