Phi-4 FastAPI 部署调用实战基于 transformers uvicorn 构建本地 LLM 推理服务self-llm 教程【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llm导读本文是《开源大模型食用指南》models/phi4 系列的第一篇实战教程核心目标是把微软开源的中型大语言模型Phi-414B在本地 Linux 环境含 AutoDL 云 GPU 实例中用 FastAPI 包装成一个可通过 HTTP 访问的推理服务。读完本文你将掌握用 modelscope 在国内网络环境下完成模型下载、用 transformers 以 bfloat16 精度加载模型、用apply_chat_template构造符合 Phi-4 对话格式的输入、用 FastAPI uvicorn 暴露POST /推理接口并分别通过 curl、Python requests、ApiPost 三种客户端完成带多轮 history 的调用与调试。这套“本地部署 HTTP 封装”的模式是后续 LangChain 接入、WebDemo 部署与 LoRA/GRPO 微调等全部进阶教程的基础。一、部署方案总览为什么用 FastAPI transformers本文选择的方案是FastAPIWeb 服务层 transformers模型推理层 uvicornASGI 服务器的组合。从 api.py 部署文档 的实现来看整个链路非常清晰HTTP POST / ──▶ FastAPI 端点 async create_item() │ 读取 JSONprompt history ▼ tokenizer.apply_chat_template(messages, add_generation_promptTrue) │ 把消息列表编码为模型输入 ▼ model.generate(model_inputs.input_ids, max_new_tokens512) │ 生成新 token截取增量部分 ▼ tokenizer.batch_decode(...) → response 文本 │ ▼ 返回 {response, history, status, time}FastAPI 的async端点天然适合承载“请求进入 → 模型推理 → 返回结果”的同步计算任务而 uvicorn 只需单 worker 即可稳定托管transformers 负责与模型权重交互device_mapauto会自动把模型分布到可用 GPU/CPU 显存上无需手动指定设备。这一“服务层与推理层解耦”的结构也正是仓库中其他模型如 ChatGLM3、Qwen 系列、InternLMFastAPI 教程的通用范式掌握本文即可举一反三。在项目层面Phi-4 属于仓库已支持的 50 开源大模型之一support_model.md 中完整登记了 FastAPI 部署、LangChain 接入、WebDemo、LoRA 微调、NER 微调、GRPO 强化学习六篇系列教程本文是这条学习路径的入口。二、环境准备2.1 基础环境要求本文基于以下已验证的软硬件环境请在学习前确认你的环境与之兼容组件版本操作系统ubuntu 22.04Python3.12CUDA12.1PyTorch2.3.0本文默认学习者已安装好以上 PyTorchCUDA环境如未安装请自行安装。若使用 AutoDL 等云 GPU 平台可直接选择带 PyTorch 的镜像再按下方步骤补齐依赖。2.2 pip 换源与依赖安装国内网络环境下先升级 pip 并把 pypi 源切换到清华镜像可显著加速依赖安装# 升级pip python -m pip install --upgrade pip # 更换 pypi 源加速库的安装 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip install transformers4.44.2 pip install huggingface-hub0.25.0 pip install accelerate0.34.2 pip install modelscope1.18.0 pip install fastapi0.115.1 pip install uvicorn0.30.6各依赖在本任务中的职责如下transformers4.44.2加载模型与分词器、执行apply_chat_template与generate的核心推理库huggingface-hub0.25.0transformers 底层访问模型仓库的基础库需与 transformers 版本匹配accelerate0.34.2提供device_mapauto自动设备分配与模型加载优化能力modelscope1.18.0从魔搭社区下载模型权重snapshot_downloadfastapi0.115.1 / uvicorn0.30.6Web 服务框架与 ASGI 服务器用于对外暴露 HTTP 接口。版本提示教程针对 Phi-4 部署验证过上述版本组合。若你计划随后进行 LoRA 微调可参考仓库中 04-Phi-4-Lora 微调.md 使用modelscope1.22.0 / transformers4.47.1 / peft0.11.1等更新组合部署与微调阶段可按需切换虚拟环境避免版本冲突。考虑到部分同学配置环境可能会遇到一些问题教程作者在 AutoDL 平台准备了 Phi-4 的环境镜像可直接基于该镜像创建实例省去手工安装依赖的步骤镜像创建方式参见 AutoDL 平台的“实例镜像/社区镜像”入口。三、模型下载使用 modelscope 的 snapshot_downloadPhi-4 权重约28GB从 Hugging Face 直接下载在国内网络下较慢且不稳定因此本文使用**魔搭社区ModelScope**作为下载源。魔搭的snapshot_download函数支持断点续传与多线程分片下载整体耗时约 1020 分钟。在/root/autodl-tmp下新建model_download.py文件并写入import torch from modelscope import snapshot_download, AutoModel, AutoTokenizer import os model_dir snapshot_download(LLM-Research/phi-4, cache_dir/root/autodl-tmp, revisionmaster)参数说明第一个参数模型名称LLM-Research/phi-4即魔搭社区中 Phi-4 的模型仓库 ID。不记得具体 ID 时可在魔搭社区搜索 “phi-4” 查看模型卡片右上角的模型名cache_dir模型下载到的本地路径必须修改为你的实际路径建议使用绝对路径models/General-Setting/03-模型下载.md 中同样强调cache_dir最好为绝对路径revision模型版本号一般默认为master。保存后在终端运行python model_download.py下载完成后权重目录将位于/root/autodl-tmp/LLM-Research/phi-4这正是下一步api.py中需要填写的模型路径。若你更习惯其他下载渠道huggingface-cli、hf-mirror 镜像、git-lfs、Openxlab可参考 models/General-Setting/03-模型下载.md 中的完整对比。四、api.py 核心代码解析把 Phi-4 封装成 HTTP 推理服务在/root/autodl-tmp下新建api.py粘贴以下代码并保存。代码附有详细注释是全文的骨架from fastapi import FastAPI, Request from transformers import AutoTokenizer, AutoModelForCausalLM import uvicorn import json import datetime import torch # 创建FastAPI应用 app FastAPI() # 处理POST请求的端点 app.post(/) async def create_item(request: Request): global model, tokenizer # 声明全局变量以便在函数内部使用模型和分词器 json_post_raw await request.json() # 获取POST请求的JSON数据 print(json_post_raw, json_post_raw) prompt json_post_raw.get(prompt) # 获取请求中的提示 history json_post_raw.get(history, []) # 获取请求中的历史消息默认为空列表 # 构建消息列表包括历史消息和当前提示 messages history [{role: user, content: prompt}] # 调用模型进行对话生成 input_ids tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) model_inputs tokenizer([input_ids], return_tensorspt).to(model.device) generated_ids model.generate(model_inputs.input_ids, max_new_tokens512) generated_ids [ output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids) ] response tokenizer.batch_decode(generated_ids, skip_special_tokensTrue)[0] # 更新历史消息将当前对话添加到历史中 updated_history messages [{role: assistant, content: response}] now datetime.datetime.now() # 获取当前时间 time now.strftime(%Y-%m-%d %H:%M:%S) # 格式化时间为字符串 # 构建响应JSON answer { response: response, history: updated_history, # 返回更新后的历史消息 status: 200, time: time } # 构建日志信息 log [ time ] , prompt: prompt , response: repr(response) print(log) # 打印日志 return answer # 返回响应 # 主函数入口 if __name__ __main__: # 加载预训练的分词器和模型 model_name_or_path /root/autodl-tmp/LLM-Research/phi-4 tokenizer AutoTokenizer.from_pretrained(model_name_or_path, use_fastFalse) tokenizer.pad_token_id tokenizer.eos_token_id 100265 model AutoModelForCausalLM.from_pretrained(model_name_or_path, device_mapauto, torch_dtypetorch.bfloat16) # 启动FastAPI应用 # 用6006端口可以将autodl的端口映射到本地从而在本地使用api uvicorn.run(app, host0.0.0.0, port6006, workers1) # 在指定端口和主机上启动应用4.1 请求处理与消息构造create_item端点端点只接受POST方法请求体为 JSON包含两个字段字段类型说明promptstring当前用户输入的问题historylist可选多轮对话历史元素为{role: user/assistant, content: ...}缺省为空列表服务端将history 当前 user 消息合并为完整的messages列表后交给tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue)渲染成 Phi-4 的对话模板字符串。这一步是 Phi-4 这类“需要 chat template”的模型的关键差异点直接用裸文本喂给模型会导致输出质量严重下降。add_generation_promptTrue会在模板末尾追加生成提示符告诉模型“现在轮到 assistant 回答”随后tokenizer([input_ids], return_tensorspt).to(model.device)把模板字符串编码为模型输入张量并搬移到模型所在设备。4.2 生成逻辑与响应组装generated_ids model.generate(model_inputs.input_ids, max_new_tokens512)max_new_tokens512控制本次生成的最大新 token 数不含输入部分。生成后通过切片output_ids[len(input_ids):]只保留增量 token再用batch_decode(..., skip_special_tokensTrue)还原成可读文本——这样可以避免把输入模板与生成提示符一起解码出来。响应中不仅返回response还返回updated_history追加了 assistant 回复的新历史方便客户端直接把它作为下一轮请求的history回传实现多轮会话的“接力”。status与time字段用于客户端侧的状态判断与日志记录服务端也会在控制台打印一条[时间] prompt:..., response:...的日志便于联调排查。4.3 模型加载的四个关键细节在主函数入口处模型加载有四处细节值得展开AutoTokenizer.from_pretrained(..., use_fastFalse)使用非快速分词器加载。Phi-4 的 tokenizer 对 chat template 支持更完整的实现该写法与仓库 02-Phi-4-Langchain接入.md 中自定义Phi_4_LLM类、03-Phi-4 WebDemo部署.md 中 Streamlit 对话应用的加载方式完全一致属于 Phi-4 系列教程统一约定的加载姿势。tokenizer.pad_token_id tokenizer.eos_token_id 100265把 pad token 与 eos token 统一设置为 token id100265。这是 Phi-4 官方分词器中约定好的特殊 token id设置后可避免 batch 生成时因缺失 pad token 导致的警告或异常。该数值同样贯穿于仓库其他 Phi-4 教程中02 文档、03 文档请勿随意改动。torch_dtypetorch.bfloat16以 bfloat16 半精度加载权重显存占用约为 fp32 的一半。14B 量级的 Phi-4 在 24GB 显存环境下即可舒适运行仓库 06-Phi-4-GRPO及swanlab可视化.md 中 unsloth 相关描述也印证了这一量级的内存需求。device_mapauto由 accelerate 自动把模型各层分配到可用设备多卡场景下自动张量并行无需手动model.to(cuda)。4.4 服务启动uvicorn 参数uvicorn.run(app, host0.0.0.0, port6006, workers1)host0.0.0.0监听所有网卡允许外部访问AutoDL 实例通常无法直连需配合端口映射见下文port6006服务端口。选择 6006 是因为 AutoDL 平台默认开放该端口的本地映射能力方便后续把远程服务的端口映射到本地浏览器/客户端workers1单 worker 即可。模型推理是显存密集型任务多 worker 反而可能导致显存不足且 FastAPI 的global model, tokenizer模式本身也只适合单进程。五、启动 API 服务与 AutoDL 端口映射5.1 启动服务在终端执行cd /root/autodl-tmp python api.py若你的api.py放在其他位置也可直接指定完整路径python /root/api.py服务默认部署在6006 端口。加载模型需要一段时间模型较大加载完毕后终端出现Uvicorn running on http://0.0.0.0:6006与Application startup complete等日志即表示成功可进入下一步调用5.2 可选AutoDL 平台 SSH 端口映射AutoDL 实例位于云端本地客户端无法直接访问0.0.0.0:6006需要先把远端 6006 端口映射到本地。在本地终端非服务器执行ssh -CNg -L 6006:127.0.0.1:6006 -p 【你的autodl机器的ssh端口】 root[你的autodl机器地址]实际示例ssh -CNg -L 6006:127.0.0.1:6006 -p 36494 rootregion-45.autodl.pro其中-p 36494与rootregion-45.autodl.pro替换为你 AutoDL 实例控制台显示的 SSH 端口与登录指令。-L 6006:127.0.0.1:6006的含义是把本地 6006 端口流量经 SSH 隧道转发到远端127.0.0.1:6006。映射建立后本地访问http://127.0.0.1:6006即等价于访问云端 API 服务。该端口映射方法是 AutoDL 场景的通用操作更多说明可参考 models/General-Setting/02-AutoDL开放端口.md。六、三种方式调用 API6.1 方式 1curl 调用curl 是最快的冒烟测试方式通过POST方法向根路径发送 JSONcurl -X POST http://127.0.0.1:6006 -H Content-Type: application/json -d {\prompt\: \你好\, \history\: []}其中history: []表示无历史对话首轮提问。返回结果中应包含response模型回答、history更新后的消息列表、status与time字段6.2 方式 2Python requests 调用在/root/autodl-tmp下新建py_api.pyimport requests url http://127.0.0.1:6006/ # 参数history可以为空列表即[]此时代表没有历史对话 payload { prompt: 刚才我们再聊什么, history: [ { role: user, content: 今天星期几 }, { role: assistant, content: 今天星期三 }, { role: user, content: 明天星期几 }, { role: assistant, content: 明天是星期四。 } ] } headers { Content-Type: application/json, Accept: */*, Accept-Encoding: gzip, deflate, br, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.94 Safari/537.37, Connection: keep-alive } response requests.request(POST, url, jsonpayload, headersheaders) print(response.text)这个示例演示了history 的真实用法请求携带了 4 条历史消息两轮问答prompt为“刚才我们再聊什么”。服务端把 history 与 prompt 合并渲染后交给模型模型基于上下文回答“我们在聊星期几”之类的承接性回复——这正是多轮对话能力的体现。history为空列表[]时则等价于单轮问答。运行python /root/autodl-tmp/py_api.py控制台将打印服务端返回的 JSON 字符串6.3 方式 3ApiPost 图形化调用对于不习惯写代码调试的同学可使用ApiPost等 HTTP 调试工具。配置如下Header 参数Content-Type: application/jsonJSON 参数Body{ prompt: 刚才我们再聊什么, history: [ { role: user, content: 今天星期几 }, { role: assistant, content: 今天星期三 }, { role: user, content: 明天星期几 }, { role: assistant, content: 明天是星期四。 } ] }请求方式选择POSTURL 填写http://127.0.0.1:6006/发送后即可在响应区看到模型回答同时可直观检查history在请求/响应中的流转三种方式的核心调用参数完全一致区别仅在客户端形态curl 适合脚本化冒烟测试requests 适合集成进业务代码ApiPost 适合手动调试请求/响应结构。七、常见问题与调试建议7.1 服务端日志定位问题每次请求后服务端控制台会打印[2026-09-11 23:45:25] , prompt:刚才我们再聊什么, response:...当客户端返回异常或内容不符预期时优先查看这行日志确认请求 JSON 是否被正确解析json_post_raw原样打印、prompt 是否正确、response 是否包含异常 token。7.2 输出长度与生成参数调节max_new_tokens512是硬编码在端点的生成上限。若需要更长回答直接修改api.py中model.generate(...)的max_new_tokens值并重启服务。仓库 03-Phi-4 WebDemo部署.md 的 Streamlit 版本将该参数做成 08192 的滑块并默认 512说明 Phi-4 支持较大的生成长度可视场景调节。7.3 类名与导入不一致导致的报错仓库 02-Phi-4-Langchain接入.md 记录了一个典型排错案例自定义 LLM 类时若文件中类名写为Phi_4却用from LLM import Phi_4_LLM导入会直接报导入错误。确保文件中定义的类名与 import 语句中的名字完全一致即可。这一经验同样适用于将本文api.py中的处理逻辑抽成模块复用的场景。7.4 显存不足14B 模型以 bfloat16 加载约需 28GB 权重显存。若出现 OOM可确认torch_dtypetorch.bfloat16是否生效device_mapauto是否把部分层卸载到 CPU会变慢但可运行或将max_new_tokens调小降低 KV Cache 占用。八、延伸FastAPI 服务在整个 Phi-4 学习路径中的位置本文搭建的 HTTP 推理服务并非终点而是仓库中 Phi-4 系列教程的基础设施进阶方向仓库教程与本文的关系LangChain 接入02-Phi-4-Langchain接入.md基于本地模型自定义Phi_4_LLM类接入 LangChain 生态做 Agent/RAG 应用WebDemo 部署03-Phi-4 WebDemo部署.md用 Streamlit 构建带界面的聊天机器人复用同样的 tokenizer/模型加载与 chat template 逻辑LoRA 微调04-Phi-4-Lora 微调.md基于 peft 对 Phi-4 高效微调让模型具备领域能力命名实体识别微调05-Phi-4-Lora 微调 命名实体识别.md把微调能力落地到具体 NER 任务GRPO 强化学习06-Phi-4-GRPO及swanlab可视化.md用 GRPO 强化学习对齐模型推理能力并通过 SwanLab 可视化训练过程你可以在本文服务的同一模型目录上继续完成以上全部步骤微调产出的 LoRA 权重可以合并回基座模型再重新以本文的api.py方式部署成新的推理服务形成“下载 → 部署 → 微调 → 再部署”的完整闭环。这也正是《开源大模型食用指南》README.md为初学者设计的从环境配置、部署使用到高效微调的阶梯式学习路径。【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Phi-4 FastAPI 部署调用实战基于 transformers uvicorn 构建本地 LLM 推理服务self-llm 教程【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llm导读本文是《开源大模型食用指南》models/phi4 系列的第一篇实战教程核心目标是把微软开源的中型大语言模型Phi-414B在本地 Linux 环境含 AutoDL 云 GPU 实例中用 FastAPI 包装成一个可通过 HTTP 访问的推理服务。读完本文你将掌握用 modelscope 在国内网络环境下完成模型下载、用 transformers 以 bfloat16 精度加载模型、用apply_chat_template构造符合 Phi-4 对话格式的输入、用 FastAPI uvicorn 暴露POST /推理接口并分别通过 curl、Python requests、ApiPost 三种客户端完成带多轮 history 的调用与调试。这套“本地部署 HTTP 封装”的模式是后续 LangChain 接入、WebDemo 部署与 LoRA/GRPO 微调等全部进阶教程的基础。一、部署方案总览为什么用 FastAPI transformers本文选择的方案是FastAPIWeb 服务层 transformers模型推理层 uvicornASGI 服务器的组合。从 api.py 部署文档 的实现来看整个链路非常清晰HTTP POST / ──▶ FastAPI 端点 async create_item() │ 读取 JSONprompt history ▼ tokenizer.apply_chat_template(messages, add_generation_promptTrue) │ 把消息列表编码为模型输入 ▼ model.generate(model_inputs.input_ids, max_new_tokens512) │ 生成新 token截取增量部分 ▼ tokenizer.batch_decode(...) → response 文本 │ ▼ 返回 {response, history, status, time}FastAPI 的async端点天然适合承载“请求进入 → 模型推理 → 返回结果”的同步计算任务而 uvicorn 只需单 worker 即可稳定托管transformers 负责与模型权重交互device_mapauto会自动把模型分布到可用 GPU/CPU 显存上无需手动指定设备。这一“服务层与推理层解耦”的结构也正是仓库中其他模型如 ChatGLM3、Qwen 系列、InternLMFastAPI 教程的通用范式掌握本文即可举一反三。在项目层面Phi-4 属于仓库已支持的 50 开源大模型之一support_model.md 中完整登记了 FastAPI 部署、LangChain 接入、WebDemo、LoRA 微调、NER 微调、GRPO 强化学习六篇系列教程本文是这条学习路径的入口。二、环境准备2.1 基础环境要求本文基于以下已验证的软硬件环境请在学习前确认你的环境与之兼容组件版本操作系统ubuntu 22.04Python3.12CUDA12.1PyTorch2.3.0本文默认学习者已安装好以上 PyTorchCUDA环境如未安装请自行安装。若使用 AutoDL 等云 GPU 平台可直接选择带 PyTorch 的镜像再按下方步骤补齐依赖。2.2 pip 换源与依赖安装国内网络环境下先升级 pip 并把 pypi 源切换到清华镜像可显著加速依赖安装# 升级pip python -m pip install --upgrade pip # 更换 pypi 源加速库的安装 pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple pip install transformers4.44.2 pip install huggingface-hub0.25.0 pip install accelerate0.34.2 pip install modelscope1.18.0 pip install fastapi0.115.1 pip install uvicorn0.30.6各依赖在本任务中的职责如下transformers4.44.2加载模型与分词器、执行apply_chat_template与generate的核心推理库huggingface-hub0.25.0transformers 底层访问模型仓库的基础库需与 transformers 版本匹配accelerate0.34.2提供device_mapauto自动设备分配与模型加载优化能力modelscope1.18.0从魔搭社区下载模型权重snapshot_downloadfastapi0.115.1 / uvicorn0.30.6Web 服务框架与 ASGI 服务器用于对外暴露 HTTP 接口。版本提示教程针对 Phi-4 部署验证过上述版本组合。若你计划随后进行 LoRA 微调可参考仓库中 04-Phi-4-Lora 微调.md 使用modelscope1.22.0 / transformers4.47.1 / peft0.11.1等更新组合部署与微调阶段可按需切换虚拟环境避免版本冲突。考虑到部分同学配置环境可能会遇到一些问题教程作者在 AutoDL 平台准备了 Phi-4 的环境镜像可直接基于该镜像创建实例省去手工安装依赖的步骤镜像创建方式参见 AutoDL 平台的“实例镜像/社区镜像”入口。三、模型下载使用 modelscope 的 snapshot_downloadPhi-4 权重约28GB从 Hugging Face 直接下载在国内网络下较慢且不稳定因此本文使用**魔搭社区ModelScope**作为下载源。魔搭的snapshot_download函数支持断点续传与多线程分片下载整体耗时约 1020 分钟。在/root/autodl-tmp下新建model_download.py文件并写入import torch from modelscope import snapshot_download, AutoModel, AutoTokenizer import os model_dir snapshot_download(LLM-Research/phi-4, cache_dir/root/autodl-tmp, revisionmaster)参数说明第一个参数模型名称LLM-Research/phi-4即魔搭社区中 Phi-4 的模型仓库 ID。不记得具体 ID 时可在魔搭社区搜索 “phi-4” 查看模型卡片右上角的模型名cache_dir模型下载到的本地路径必须修改为你的实际路径建议使用绝对路径models/General-Setting/03-模型下载.md 中同样强调cache_dir最好为绝对路径revision模型版本号一般默认为master。保存后在终端运行python model_download.py下载完成后权重目录将位于/root/autodl-tmp/LLM-Research/phi-4这正是下一步api.py中需要填写的模型路径。若你更习惯其他下载渠道huggingface-cli、hf-mirror 镜像、git-lfs、Openxlab可参考 models/General-Setting/03-模型下载.md 中的完整对比。四、api.py 核心代码解析把 Phi-4 封装成 HTTP 推理服务在/root/autodl-tmp下新建api.py粘贴以下代码并保存。代码附有详细注释是全文的骨架from fastapi import FastAPI, Request from transformers import AutoTokenizer, AutoModelForCausalLM import uvicorn import json import datetime import torch # 创建FastAPI应用 app FastAPI() # 处理POST请求的端点 app.post(/) async def create_item(request: Request): global model, tokenizer # 声明全局变量以便在函数内部使用模型和分词器 json_post_raw await request.json() # 获取POST请求的JSON数据 print(json_post_raw, json_post_raw) prompt json_post_raw.get(prompt) # 获取请求中的提示 history json_post_raw.get(history, []) # 获取请求中的历史消息默认为空列表 # 构建消息列表包括历史消息和当前提示 messages history [{role: user, content: prompt}] # 调用模型进行对话生成 input_ids tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue) model_inputs tokenizer([input_ids], return_tensorspt).to(model.device) generated_ids model.generate(model_inputs.input_ids, max_new_tokens512) generated_ids [ output_ids[len(input_ids):] for input_ids, output_ids in zip(model_inputs.input_ids, generated_ids) ] response tokenizer.batch_decode(generated_ids, skip_special_tokensTrue)[0] # 更新历史消息将当前对话添加到历史中 updated_history messages [{role: assistant, content: response}] now datetime.datetime.now() # 获取当前时间 time now.strftime(%Y-%m-%d %H:%M:%S) # 格式化时间为字符串 # 构建响应JSON answer { response: response, history: updated_history, # 返回更新后的历史消息 status: 200, time: time } # 构建日志信息 log [ time ] , prompt: prompt , response: repr(response) print(log) # 打印日志 return answer # 返回响应 # 主函数入口 if __name__ __main__: # 加载预训练的分词器和模型 model_name_or_path /root/autodl-tmp/LLM-Research/phi-4 tokenizer AutoTokenizer.from_pretrained(model_name_or_path, use_fastFalse) tokenizer.pad_token_id tokenizer.eos_token_id 100265 model AutoModelForCausalLM.from_pretrained(model_name_or_path, device_mapauto, torch_dtypetorch.bfloat16) # 启动FastAPI应用 # 用6006端口可以将autodl的端口映射到本地从而在本地使用api uvicorn.run(app, host0.0.0.0, port6006, workers1) # 在指定端口和主机上启动应用4.1 请求处理与消息构造create_item端点端点只接受POST方法请求体为 JSON包含两个字段字段类型说明promptstring当前用户输入的问题historylist可选多轮对话历史元素为{role: user/assistant, content: ...}缺省为空列表服务端将history 当前 user 消息合并为完整的messages列表后交给tokenizer.apply_chat_template(messages, tokenizeFalse, add_generation_promptTrue)渲染成 Phi-4 的对话模板字符串。这一步是 Phi-4 这类“需要 chat template”的模型的关键差异点直接用裸文本喂给模型会导致输出质量严重下降。add_generation_promptTrue会在模板末尾追加生成提示符告诉模型“现在轮到 assistant 回答”随后tokenizer([input_ids], return_tensorspt).to(model.device)把模板字符串编码为模型输入张量并搬移到模型所在设备。4.2 生成逻辑与响应组装generated_ids model.generate(model_inputs.input_ids, max_new_tokens512)max_new_tokens512控制本次生成的最大新 token 数不含输入部分。生成后通过切片output_ids[len(input_ids):]只保留增量 token再用batch_decode(..., skip_special_tokensTrue)还原成可读文本——这样可以避免把输入模板与生成提示符一起解码出来。响应中不仅返回response还返回updated_history追加了 assistant 回复的新历史方便客户端直接把它作为下一轮请求的history回传实现多轮会话的“接力”。status与time字段用于客户端侧的状态判断与日志记录服务端也会在控制台打印一条[时间] prompt:..., response:...的日志便于联调排查。4.3 模型加载的四个关键细节在主函数入口处模型加载有四处细节值得展开AutoTokenizer.from_pretrained(..., use_fastFalse)使用非快速分词器加载。Phi-4 的 tokenizer 对 chat template 支持更完整的实现该写法与仓库 02-Phi-4-Langchain接入.md 中自定义Phi_4_LLM类、03-Phi-4 WebDemo部署.md 中 Streamlit 对话应用的加载方式完全一致属于 Phi-4 系列教程统一约定的加载姿势。tokenizer.pad_token_id tokenizer.eos_token_id 100265把 pad token 与 eos token 统一设置为 token id100265。这是 Phi-4 官方分词器中约定好的特殊 token id设置后可避免 batch 生成时因缺失 pad token 导致的警告或异常。该数值同样贯穿于仓库其他 Phi-4 教程中02 文档、03 文档请勿随意改动。torch_dtypetorch.bfloat16以 bfloat16 半精度加载权重显存占用约为 fp32 的一半。14B 量级的 Phi-4 在 24GB 显存环境下即可舒适运行仓库 06-Phi-4-GRPO及swanlab可视化.md 中 unsloth 相关描述也印证了这一量级的内存需求。device_mapauto由 accelerate 自动把模型各层分配到可用设备多卡场景下自动张量并行无需手动model.to(cuda)。4.4 服务启动uvicorn 参数uvicorn.run(app, host0.0.0.0, port6006, workers1)host0.0.0.0监听所有网卡允许外部访问AutoDL 实例通常无法直连需配合端口映射见下文port6006服务端口。选择 6006 是因为 AutoDL 平台默认开放该端口的本地映射能力方便后续把远程服务的端口映射到本地浏览器/客户端workers1单 worker 即可。模型推理是显存密集型任务多 worker 反而可能导致显存不足且 FastAPI 的global model, tokenizer模式本身也只适合单进程。五、启动 API 服务与 AutoDL 端口映射5.1 启动服务在终端执行cd /root/autodl-tmp python api.py若你的api.py放在其他位置也可直接指定完整路径python /root/api.py服务默认部署在6006 端口。加载模型需要一段时间模型较大加载完毕后终端出现Uvicorn running on http://0.0.0.0:6006与Application startup complete等日志即表示成功可进入下一步调用5.2 可选AutoDL 平台 SSH 端口映射AutoDL 实例位于云端本地客户端无法直接访问0.0.0.0:6006需要先把远端 6006 端口映射到本地。在本地终端非服务器执行ssh -CNg -L 6006:127.0.0.1:6006 -p 【你的autodl机器的ssh端口】 root[你的autodl机器地址]实际示例ssh -CNg -L 6006:127.0.0.1:6006 -p 36494 rootregion-45.autodl.pro其中-p 36494与rootregion-45.autodl.pro替换为你 AutoDL 实例控制台显示的 SSH 端口与登录指令。-L 6006:127.0.0.1:6006的含义是把本地 6006 端口流量经 SSH 隧道转发到远端127.0.0.1:6006。映射建立后本地访问http://127.0.0.1:6006即等价于访问云端 API 服务。该端口映射方法是 AutoDL 场景的通用操作更多说明可参考 models/General-Setting/02-AutoDL开放端口.md。六、三种方式调用 API6.1 方式 1curl 调用curl 是最快的冒烟测试方式通过POST方法向根路径发送 JSONcurl -X POST http://127.0.0.1:6006 -H Content-Type: application/json -d {\prompt\: \你好\, \history\: []}其中history: []表示无历史对话首轮提问。返回结果中应包含response模型回答、history更新后的消息列表、status与time字段6.2 方式 2Python requests 调用在/root/autodl-tmp下新建py_api.pyimport requests url http://127.0.0.1:6006/ # 参数history可以为空列表即[]此时代表没有历史对话 payload { prompt: 刚才我们再聊什么, history: [ { role: user, content: 今天星期几 }, { role: assistant, content: 今天星期三 }, { role: user, content: 明天星期几 }, { role: assistant, content: 明天是星期四。 } ] } headers { Content-Type: application/json, Accept: */*, Accept-Encoding: gzip, deflate, br, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.6261.94 Safari/537.37, Connection: keep-alive } response requests.request(POST, url, jsonpayload, headersheaders) print(response.text)这个示例演示了history 的真实用法请求携带了 4 条历史消息两轮问答prompt为“刚才我们再聊什么”。服务端把 history 与 prompt 合并渲染后交给模型模型基于上下文回答“我们在聊星期几”之类的承接性回复——这正是多轮对话能力的体现。history为空列表[]时则等价于单轮问答。运行python /root/autodl-tmp/py_api.py控制台将打印服务端返回的 JSON 字符串6.3 方式 3ApiPost 图形化调用对于不习惯写代码调试的同学可使用ApiPost等 HTTP 调试工具。配置如下Header 参数Content-Type: application/jsonJSON 参数Body{ prompt: 刚才我们再聊什么, history: [ { role: user, content: 今天星期几 }, { role: assistant, content: 今天星期三 }, { role: user, content: 明天星期几 }, { role: assistant, content: 明天是星期四。 } ] }请求方式选择POSTURL 填写http://127.0.0.1:6006/发送后即可在响应区看到模型回答同时可直观检查history在请求/响应中的流转三种方式的核心调用参数完全一致区别仅在客户端形态curl 适合脚本化冒烟测试requests 适合集成进业务代码ApiPost 适合手动调试请求/响应结构。七、常见问题与调试建议7.1 服务端日志定位问题每次请求后服务端控制台会打印[2026-09-11 23:45:25] , prompt:刚才我们再聊什么, response:...当客户端返回异常或内容不符预期时优先查看这行日志确认请求 JSON 是否被正确解析json_post_raw原样打印、prompt 是否正确、response 是否包含异常 token。7.2 输出长度与生成参数调节max_new_tokens512是硬编码在端点的生成上限。若需要更长回答直接修改api.py中model.generate(...)的max_new_tokens值并重启服务。仓库 03-Phi-4 WebDemo部署.md 的 Streamlit 版本将该参数做成 08192 的滑块并默认 512说明 Phi-4 支持较大的生成长度可视场景调节。7.3 类名与导入不一致导致的报错仓库 02-Phi-4-Langchain接入.md 记录了一个典型排错案例自定义 LLM 类时若文件中类名写为Phi_4却用from LLM import Phi_4_LLM导入会直接报导入错误。确保文件中定义的类名与 import 语句中的名字完全一致即可。这一经验同样适用于将本文api.py中的处理逻辑抽成模块复用的场景。7.4 显存不足14B 模型以 bfloat16 加载约需 28GB 权重显存。若出现 OOM可确认torch_dtypetorch.bfloat16是否生效device_mapauto是否把部分层卸载到 CPU会变慢但可运行或将max_new_tokens调小降低 KV Cache 占用。八、延伸FastAPI 服务在整个 Phi-4 学习路径中的位置本文搭建的 HTTP 推理服务并非终点而是仓库中 Phi-4 系列教程的基础设施进阶方向仓库教程与本文的关系LangChain 接入02-Phi-4-Langchain接入.md基于本地模型自定义Phi_4_LLM类接入 LangChain 生态做 Agent/RAG 应用WebDemo 部署03-Phi-4 WebDemo部署.md用 Streamlit 构建带界面的聊天机器人复用同样的 tokenizer/模型加载与 chat template 逻辑LoRA 微调04-Phi-4-Lora 微调.md基于 peft 对 Phi-4 高效微调让模型具备领域能力命名实体识别微调05-Phi-4-Lora 微调 命名实体识别.md把微调能力落地到具体 NER 任务GRPO 强化学习06-Phi-4-GRPO及swanlab可视化.md用 GRPO 强化学习对齐模型推理能力并通过 SwanLab 可视化训练过程你可以在本文服务的同一模型目录上继续完成以上全部步骤微调产出的 LoRA 权重可以合并回基座模型再重新以本文的api.py方式部署成新的推理服务形成“下载 → 部署 → 微调 → 再部署”的完整闭环。这也正是《开源大模型食用指南》README.md为初学者设计的从环境配置、部署使用到高效微调的阶梯式学习路径。【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
)
