简介:本文面向希望动手实践本地大模型的开发者:用一台普通电脑即可完成模型部署,并通过 Python 调用完成第一次对话。文章涵盖硬件评估、推理框架安装与启动、模型下载、调用参数配置,以及调用失败、显存不足等问题的排查思路,帮助你打通“部署—调用—调优—运维”的完整链路。
随着开源大模型生态快速发展,越来越多开发者希望在本地计算机或自有服务器上运行大模型。相比调用云端API,本地部署具有三点优势:
本教程是“大模型实战”系列的第 01 篇,目标是带你在一台普通计算机上完成本地大模型的部署与 Python 调用。完成后,你将能够:
适用读者:具备基础 Python 编程能力、对命令行有初步了解的开发者与运维人员;计划搭建内部 AI 助手的技术负责人;希望保护数据隐私的企业用户。硬件方面,拥有 8 GB 以上内存的电脑即可入门,拥有独立显卡体验更佳。
本教程采用“本地推理框架 + 开源模型权重 + Python HTTP 客户端”的三层架构:
推理框架会在后台启动一个本地服务并持续监听指定端口。Python 脚本把提问以 JSON 格式发送到该端口,模型生成回答后,再以 JSON 返回。
为兼顾易用性与可移植性,本教程优先使用某款以“开箱即用”著称的本地推理框架(下称“本地推理框架”)完成部署,采用“先跑通、再理解”的方式入门。后续可在同一套调用接口上平滑切换到更侧重高吞吐的推理引擎。
说明:本地推理框架、开源模型托管平台、模型社区均为通用技术产物的统称,并非特指某一款软件或网站。各版本界面、参数可能不同,请以实际使用版本的官方文档为准。
| 硬件 | 最低配置 | 推荐配置 | 说明 |
|---|---|---|---|
| 内存 | 8 GB | 16 GB 及以上 | 无独立显卡时,模型主要加载到内存中 |
| 显存 | 可选 | 8 GB 及以上 | 决定能流畅运行多大的模型 |
| 处理器 | 支持 64 位的主流 x86 或 ARM 处理器 | 多核处理器 | ARM 架构需确认框架是否提供对应版本 |
| 存储 | 10 GB 可用空间 | 50 GB 及以上 | 每个模型文件通常为数 GB 至数十 GB |
| 系统 | Linux、Windows 或 macOS | 与框架支持列表一致 | 安装前核对版本要求 |
python --version、pip --version 能正常输出版本号;开源模型权重主要有两个来源:
网络提示:直连海外模型平台可能受网络环境限制,导致下载缓慢或失败,不建议为此目的使用代理加速工具。推荐优先使用国内模型社区,或官方提供的离线安装包;也可以让同事在可正常访问的环境中提前下载模型文件,再拷贝到本地导入。
部署前先掌握本机资源情况,再据此选型:
# Linux / macOS:查看 CPU 核数与内存容量nprocfree -h# Linux:查看 NVIDIA 显卡及显存nvidia-smi# 不区分操作系统:使用通用系统信息工具查看硬件python -m pip install psutil
# Windows:查看内存、显卡与磁盘空间Get-CimInstance Win32_ComputerSystem | Select-Object TotalPhysicalMemoryGet-CimInstance Win32_VideoController | Select-Object Name, AdapterRAMGet-PSDrive C
记录以下三个关键数据:
做什么:根据上一步获取的资源情况,选择参数规模合适的模型和量化精度。
为什么这么做:模型参数量与显存、内存占用直接相关。大致估算公式为:
权重体积(GB)≈ 参数量(单位:十亿)× 每个参数的字节数FP32:每个参数 4 字节 FP16 / BF16:每个参数 2 字节INT8 量化:约 1 字节 INT4 量化:约 0.5 字节
以 70 亿(7B)参数模型为例:FP16 下权重约 14 GB,4 bit 量化后约 4 GB。此外,模型运行还需要上下文缓存(KV Cache)与框架自身的开销,建议预留 20%~30% 的余量。
量化是指用更少的比特表示模型参数,以更少的内存获得接近原精度的效果。量化等级越低,模型体积越小、速度越快,但生成质量也可能下降。
选型参考:
| 可用显存 / 内存 | 建议参数规模(4 bit 量化) | 适用场景 |
|---|---|---|
| 4 GB 左右 | 1B~3B | 轻量问答、文本摘要,可用纯 CPU 推理 |
| 8 GB 左右 | 7B~9B | 通用对话、代码辅助,入门首选 |
| 16 GB 及以上 | 14B~32B | 复杂推理、长文本理解 |
| 24 GB 及以上 | 70B 或混合专家(MoE)架构模型 | 高质量生成,接近云端模型水平 |
注意:显存不足时,框架可把部分计算交给内存与 CPU,但速度会明显下降。
做什么:通过官方提供的安装方式部署本地推理框架,随后启动服务。
为什么这么做:框架是模型与调用程序之间的“桥梁”,负责加载权重、调度计算资源并暴露 HTTP 接口。
以类 UNIX 系统为例:
# 执行官方提供的安装脚本(实际地址请以框架官方文档为准)curl -fsSL <官方安装地址> | sh# 验证是否安装成功<本地推理框架命令> --version
以 Windows 为例:下载官方安装包,双击安装后,框架通常会随系统自动启动。
安装完成后,用简单提问做一次“冒烟测试”:
<本地推理框架命令> run <模型标识>>>> 用一句话介绍你自己
服务端日志会依次显示“读取模型、加载到显存、等待请求”等信息。首次加载需要几十秒到数分钟,请耐心等待。
注意:
做什么:通过框架命令拉取模型,或导入已下载的模型文件。
方式一:在线拉取
# 语法:<本地推理框架命令> pull <模型标识># 模型标识通常由“系列名称 + 参数规模 + 量化方式”组成,常见量化后缀如 q4 表示 4 bit 量化。# 示例:拉取某 70 亿参数模型的 4 bit 量化版本<本地推理框架命令> pull <模型标识>
方式二:从国内模型社区获取
方式三:导入已有的模型文件
适合无外网、需提前准备或需要统一管控的离线场景:
# 1. 创建模型描述文件 ModelFile,指定量化权重来源FROM ./model-file.ggufPARAMETER temperature 0.7# 2. 基于描述文件创建模型(名称可自定义)<本地推理框架命令> create my-local-model -f ModelFile# 3. 运行刚创建的模型<本地推理框架命令> run my-local-model
注意:不同来源的模型文件格式可能不同(如 GGUF、safetensors 等)。请先确认目标框架支持的格式,必要时借助通用的格式转换工具转换。
做什么:确认框架已在本机端口上监听,并能通过 HTTP 返回模型列表。
# 查看监听端口(Windows 上将 netstat 替换为 ss 或 Get-NetTCPConnection)netstat -ano | findstr LISTENING# 调用模型列表接口,验证 HTTP 服务可用curl http://localhost:<端口>/api/tags
如果返回包含模型名称的 JSON 数据,说明服务正常。
注意:列表接口中的模型名称,就是后续 Python 调用时请求体里的 model 字段取值。务必与列表中显示的名称完全一致,包括版本与量化后缀。
做什么:新建 Python 文件,使用标准库向本地推理服务发送请求。
为什么这么做:本地推理框架对外提供标准 HTTP 接口,任何能发送 HTTP 请求的语言都可以调用。使用标准库无需安装额外依赖,便于理解请求与响应的完整过程。
import jsonimport urllib.request# 基础地址:localhost 表示本机,11434 为本地推理框架的默认端口,若被占用可修改BASE_URL = "http://localhost:11434"def ask(model: str, prompt: str, temperature: float = 0.7, num_predict: int = 512) -> str:"""向本地推理框架的对话接口发送一次请求,并返回模型回答。"""payload = {"model": model, # 模型标识,需与模型列表中的名称一致"messages": [ # 对话历史,role 可取 system/user/assistant{"role": "system", "content": "你是一名严谨的技术助手,回答简洁准确。"},{"role": "user", "content": prompt},],"stream": False, # False 表示一次性返回完整结果"options": { # 采样参数放在 options 字段中"temperature": temperature,"num_predict": num_predict,},}# 以 POST 方式发送 JSON 数据request = urllib.request.Request(f"{BASE_URL}/api/chat",data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),headers={"Content-Type": "application/json"},method="POST",)with urllib.request.urlopen(request, timeout=300) as response:result = json.loads(response.read().decode("utf-8"))# 本地推理框架的响应中,message.content 为模型生成的文本return result.get("message", {}).get("content", "")if __name__ == "__main__":answer = ask("my-local-model", "用三句话解释什么是模型量化。")print(answer)
运行脚本:
python local_chat.py
各字段作用:
| 字段 | 作用 | 典型取值 |
|---|---|---|
| model | 指定调用的模型 | 需与模型列表中的名称一致 |
| messages | 多轮对话上下文 | 列表,每项为 role + content |
| stream | 是否流式返回 | true / false |
| options | 采样与长度控制参数 | 见步骤七 |
| timeout | 客户端等待时间 | 首次推理建议 300 秒以上 |
做什么:将 stream 设为 True,逐块读取并实时打印。
为什么这么做:一次性返回时,用户需等待整段答案生成完毕才能看到内容;流式输出类似打字机效果,首字响应快、体验更好。
import jsonimport urllib.requestdef ask_stream(model: str, prompt: str) -> None:payload = {"model": model,"messages": [{"role": "user", "content": prompt}],"stream": True,}request = urllib.request.Request(f"{BASE_URL}/api/chat",data=json.dumps(payload, ensure_ascii=False).encode("utf-8"),headers={"Content-Type": "application/json"},method="POST",)with urllib.request.urlopen(request, timeout=300) as response:# 流式响应为逐行发送的 JSON(常见格式为 JSONL 或 SSE)for raw_line in response:line = raw_line.decode("utf-8").strip()if not line:continue# SSE 格式需先去掉 data: 前缀,并忽略 [DONE] 结束标记if line.startswith("data:"):line = line[len("data:"):].strip()if line == "[DONE]":breaktry:chunk = json.loads(line)except json.JSONDecodeError:continuecontent = chunk.get("message", {}).get("content", "")if content:print(content, end="", flush=True) # flush 确保内容立即显示print()if __name__ == "__main__":ask_stream("my-local-model", "写一首关于程序员调试代码的短诗。")
做什么:调用框架提供的、与主流大模型服务商接口规范兼容的对话接口。
为什么这么做:兼容接口遵循业界通用的“对话补全”格式,与主流大模型服务商的云端接口高度一致。已使用相关 SDK 的项目只需修改 base_url,即可把请求指向本地服务,验证阶段无需改动业务代码。
# 安装官方客户端库:pip install openaifrom openai import OpenAIclient = OpenAI(base_url="http://localhost:11434/v1", # 指向本地服务api_key="local", # 兼容接口要求填写,本地服务不校验,占位即可)completion = client.chat.completions.create(model="my-local-model",messages=[{"role": "system", "content": "你是资深 Python 讲师。"},{"role": "user", "content": "如何用一行代码反转一个列表?"},],temperature=0.7,stream=False,)print(completion.choices[0].message.content)
注意:本地兼容接口一般不需要真实的 API 密钥,占位字符串即可。但生产环境中,仍建议为服务配置访问认证,避免被内网其他主机直接调用。
调用质量和速度与以下参数密切相关:
| 参数 | 含义 | 常见取值 | 调整建议 |
|---|---|---|---|
| temperature | 随机性,值越大越发散 | 0~2,常用 0.7 | 代码、数学、信息抽取等任务设为 0~0.3 |
| top_p | 核采样,只从累积概率最高的一部分词中采样 | 0~1,常用 0.9 | 与 temperature 二选一为主,不必同时大幅调低 |
| top_k | 只保留概率最高的 K 个候选词 | 常见 20~40 | 与 top_p 配合使用 |
| num_ctx | 上下文窗口长度 | 视模型支持范围而定,常见 4096 起 | 越长越占显存,够用即可 |
| num_predict | 单次最多生成的 token 数 | 128~4096 | 输出被截断时调大 |
| repeat_penalty | 重复惩罚 | 1.0~1.5 | 回答反复啰嗦时适当调高 |
| seed | 随机种子 | 整数 | 固定后可复现结果,便于测试对比 |
配置风险:temperature 设得过高容易导致答案前后矛盾;num_ctx 设置超过模型支持上限,可能加载失败或效果下降;num_predict 过小会导致回答不完整。
做什么:每轮把完整的消息列表发送给模型,包括 system 提示、历史对话以及本轮用户输入。
为什么这么做:本地推理框架在单次请求中默认无状态,不会自动记忆上一轮对话。多轮对话能力由调用方维护的消息列表实现。
messages = [{"role": "system", "content": "你是一位耐心的编程导师。"}]while True:user_input = input("你:").strip()if user_input in ("exit", "quit"):breakmessages.append({"role": "user", "content": user_input})# 发起请求时使用完整的 messages 列表# answer = ask_with_messages("my-local-model", messages)# messages.append({"role": "assistant", "content": answer})print("助手:") # 此处替换为实际调用结果
注意:对话越长,消耗的 token 越多,显存占用和推理时间也会随之增加。可按需只保留最近 N 轮对话,或对早期内容做摘要压缩。
做什么:让推理框架随系统启动,并自动重启异常退出的进程。
# Linux 示例:将以下内容保存为 /etc/systemd/system/local-llm.service[Unit]Description=Local LLM Inference ServiceAfter=network.target[Service]Type=simple# 使用专用普通用户运行,避免高权限风险User=llmuser# 如需限制对外监听范围,可在此追加监听地址与跨域来源的环境变量Environment="OLLAMA_HOST=127.0.0.1:11434"# 替换为实际安装路径ExecStart=/usr/local/bin/ollama serveRestart=on-failureRestartSec=5s[Install]WantedBy=multi-user.target
启用并检查状态:
sudo systemctl daemon-reloadsudo systemctl enable --now local-llmsudo systemctl status local-llm
完成上述步骤后,可按以下清单逐项确认:
| 现象 | 可能原因 | 排查思路 |
|---|---|---|
| 连接被拒绝 | 服务未启动、端口被占用或填错 | 查看服务状态与端口监听情况 |
| 找不到模型(model not found) | 模型名称不一致 | 用列表接口核对名称,包括量化后缀 |
| 显存不足 / 内存溢出 | 模型超出硬件容量 | 换用更小或更低精度的量化版本,缩短上下文长度 |
| 首次响应极慢 | 模型首次加载、CPU 推理 | 观察日志中加载进度,预热模型,或启用 GPU |
| 输出被截断 | num_predict 太小 | 调大生成长度参数 |
| 中文输出异常 | 下载中断导致文件损坏 | 重新下载并校验文件大小与校验值 |
| 安装脚本无法执行 | 网络受限或权限不足 | 改用离线安装包,或使用具备相应权限的账号 |
| 回答明显变慢 | 显存不足,部分计算回退到内存 | 监控显存占用,降低量化精度或换小模型 |
| 部分应用无法连接 | 跨域或监听地址限制 | 在配置中允许对应来源,或将监听地址改为 0.0.0.0 |
通用排查顺序:服务状态 → 监听端口 → 接口返回 → 请求参数 → 模型本身。
本教程完成了以下工作:
后续可继续深入的方向:
先让模型在本机“跑起来”,再逐步走向工程化与规模化,是本地大模型落地的稳妥路径。