self-llm 实战：基于 FastAPI 部署调用 Phi-3-mini-4k-instruct 完整指南

self-llm 实战基于 FastAPI 部署调用 Phi-3-mini-4k-instruct 完整指南【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llmPhi-3-mini-4k-instruct 是微软 Phi-3 系列中 3.8B 参数、支持 4K 上下文的轻量级对话模型非常适合在 24G 显存级别的单卡环境如 AutoDL 上的 RTX 3090中进行部署与二次开发。本文以开源大模型实战仓库 self-llm 中的 Phi-3 FastApi 部署教程 为骨架完整演示从环境准备、模型下载到编写 FastAPI 推理服务、curl/Postman 联调、SSH 端口映射的端到端流程。读完本文你将能够在一台 Linux GPU 服务器上独立搭建一个可被任意 HTTP 客户端调用的 Phi-3 对话 API 服务并理解其底层调用链与常见排错点。一、部署方案概览与技术选型在动手之前先明确本次部署的核心链路模型LLM-Research/Phi-3-mini-4k-instruct约 8 GB 权重通过 ModelScope 的snapshot_download下载到本地磁盘推理框架Hugging Facetransformers通过AutoTokenizerAutoModelForCausalLM加载模型用tokenizer.apply_chat_template组装对话模板、model.generate执行生成服务框架FastAPIuvicorn对外暴露一个POST /接口接收 JSON 格式的prompt与history字段返回包含response、status、time的 JSON 响应访问方式服务默认监听0.0.0.0:6006在 AutoDL 等云端环境通过 SSH 端口映射到本地后可用 curl、Postman、requests 等任意 HTTP 客户端调用。从仓库中的 Phi-3-mini-4k-Instruct-Lora.ipynb 可以看到该模型的底层结构为Phi3ForCausalLM32 层Phi3DecoderLayer、隐藏维度 3072、词表大小 32064padding_idx32000注意力部分采用qkv_proj合并线性层3072→9216MLP 采用gate_up_proj合并线性层配合 SiLU 激活。理解这一结构有助于后续排查加载报错以及为 LoRA 微调选择正确的target_modules。二、环境准备2.1 租赁 GPU 机器与选择镜像在 AutoDL 平台租赁一台3090 等 24G 显存的显卡机器。创建实例时镜像选择PyTorch -- 2.0.0 -- 3.8(ubuntu20.04) -- 11.8如下图所示。说明11.3 及以上版本的 CUDA 镜像通常均可满足本教程需求上图来自仓库中 InternLM2 FastAPI 部署文档 的通用环境配置示例与本教程的镜像选择要求一致。租用成功后打开服务器的JupyterLab在其中的终端里完成环境配置、模型下载和运行演示。2.2 创建工作目录创建本次 phi3 实践的工作目录/root/autodl-tmp/phi3# 创建工作目录 mkdir -p /root/autodl-tmp/phi32.3 安装依赖依次执行以下命令先升级 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 fastapi0.104.1 pip install uvicorn0.24.0.post1 pip install requests2.25.1 pip install modelscope1.9.5 pip install streamlit1.24.0 pip install sentencepiece0.1.99 pip install accelerate0.24.1各依赖的用途依赖包版本用途fastapi0.104.1提供 Web 框架定义POST /接口与 JSON 请求/响应处理uvicorn0.24.0.post1ASGI 服务器负责真正监听端口、启动服务进程requests2.25.1本地联调时通过 HTTP 调用 APImodelscope1.9.5从 ModelScope 下载模型权重streamlit1.24.0本教程 FastAPI 部署用不到为仓库后续 WebDemo 部署预留sentencepiece0.1.99Phi-3 分词器所需的底层子词库accelerate0.24.1支持device_map自动设备分配简化模型加载2.4 检查并升级 transformers 版本Phi-3 模型的加载对transformers版本有明确要求本教程要求4.41.0.dev0版本。先检查当前环境中 transformers 的版本pip list | grep transformers如果版本不对可以通过以下命令升级卸载旧版本后直接安装 transformers 主分支开发版# phi3升级transformers为4.41.0.dev0版本 pip uninstall -y transformers pip install githttps://github.com/huggingface/transformers注意事项4.41.0.dev0是开发版务必先通过pip list | grep transformers确认版本。该版本要求来自官方发布 Phi-3 时的 transformers 适配版本若版本过低会报出类似KeyError: phi3的模型类型找不到错误。三、模型下载使用 ModelScope 的snapshot_download函数下载模型第一个参数为模型名称参数cache_dir为模型的下载路径。在/root/autodl-tmp路径下新建download.py文件输入以下内容粘贴后记得保存文件# 模型下载 from modelscope import snapshot_download model_dir snapshot_download(LLM-Research/Phi-3-mini-4k-instruct, cache_dir/root/autodl-tmp/phi3, revisionmaster)然后运行以下命令执行下载python /root/autodl-tmp/download.py模型大小约8 GB视网络情况下载大概需要10~15 分钟。下载完成后权重文件位于/root/autodl-tmp/phi3/model/LLM-Research/Phi-3-mini-4k-instruct目录下——注意snapshot_download会在cache_dir下自动追加model/模型名的目录层级这个路径正是后续api.py中model_name_or_path需要指向的位置。四、编写 FastAPI 推理服务在/root/autodl-tmp路径下新建api.py文件输入以下内容粘贴代码后记得保存文件from fastapi import FastAPI, Request from transformers import AutoTokenizer, AutoModelForCausalLM, GenerationConfig import uvicorn import json import datetime import torch # 设置设备参数 DEVICE cuda # 使用CUDA DEVICE_ID 0 # CUDA设备ID如果未设置则为空 CUDA_DEVICE f{DEVICE}:{DEVICE_ID} if DEVICE_ID else DEVICE # 组合CUDA设备信息 # 清理GPU内存函数 def torch_gc(): if torch.cuda.is_available(): # 检查是否可用CUDA with torch.cuda.device(CUDA_DEVICE): # 指定CUDA设备 torch.cuda.empty_cache() # 清空CUDA缓存 torch.cuda.ipc_collect() # 收集CUDA内存碎片 # 创建FastAPI应用 app FastAPI() # 处理POST请求的端点 app.post(/) async def create_item(request: Request): global model, tokenizer # 声明全局变量以便在函数内部使用模型和分词器 json_post_raw await request.json() # 获取POST请求的JSON数据 json_post json.dumps(json_post_raw) # 将JSON数据转换为字符串 json_post_list json.loads(json_post) # 将字符串转换为Python对象 prompt json_post_list.get(prompt) # 获取请求中的提示 history json_post_list.get(history, []) # 获取请求中的历史记录 print(prompt) messages [ {role: user, content: prompt} ] # 调用模型进行对话生成 input_ids tokenizer.apply_chat_template(conversationmessages, tokenizeTrue, add_generation_promptTrue, return_tensorspt) output_ids model.generate(input_ids.to(cuda),max_new_tokens2048) response tokenizer.decode(output_ids[0][input_ids.shape[1]:], skip_special_tokensTrue) now datetime.datetime.now() # 获取当前时间 time now.strftime(%Y-%m-%d %H:%M:%S) # 格式化时间为字符串 # 构建响应JSON answer { response: response, status: 200, time: time } # 构建日志信息 log [ time ] , prompt: prompt , response: repr(response) print(log) # 打印日志 torch_gc() # 执行GPU内存清理 return answer # 返回响应 # 主函数入口 if __name__ __main__: # 加载预训练的分词器和模型 model_name_or_path /root/autodl-tmp/phi3/model/LLM-Research/Phi-3-mini-4k-instruct tokenizer AutoTokenizer.from_pretrained(model_name_or_path) model AutoModelForCausalLM.from_pretrained(model_name_or_path, device_mapcuda, torch_dtypeauto, trust_remote_codeTrue, ).eval() # 启动FastAPI应用 # 用6006端口可以将autodl的端口映射到本地从而在本地使用api uvicorn.run(app, host0.0.0.0, port6006, workers1) # 在指定端口和主机上启动应用下面逐段拆解这段代码的关键设计1设备与显存管理DEVICE cuda与DEVICE_ID 0组合出CUDA_DEVICE cuda:0明确指定推理使用的 GPU。torch_gc()在每次请求结束后调用通过torch.cuda.empty_cache()清空缓存、torch.cuda.ipc_collect()回收显存碎片避免长时间服务下显存持续膨胀。这是长稳运行服务的重要一环。2接口与请求解析app.post(/)注册根路径的 POST 端点。请求体为 JSON通过await request.json()读取后依次经json.dumps、json.loads标准化为 Python 字典。从请求中取出prompt必填和history可选默认空列表两个字段。本教程实现中将prompt包装为单轮messages对话history字段保留是为了与后续多轮对话扩展兼容。3对话模板与生成tokenizer.apply_chat_template(conversationmessages, tokenizeTrue, add_generation_promptTrue, return_tensorspt)是 Phi-3 部署中的关键一步它会按照模型内置的 chat template 将消息列表组装为input_ids并在末尾追加|assistant|\n生成提示return_tensorspt返回可直接送入模型的 PyTorch 张量。从仓库 Lora 微调教程 中可以确认 Phi-3 的 Prompt Template 格式为|system| You are a helpful assistant|end| |user| 你是谁|end| |assistant| 我是一个有用的助手。|end|model.generate(input_ids.to(cuda), max_new_tokens2048)执行自回归生成max_new_tokens2048限制最大新生成 token 数可根据任务调大或调小。tokenizer.decode(output_ids[0][input_ids.shape[1]:], skip_special_tokensTrue)通过切片去掉输入部分的 token只解码新生成的部分并跳过|endoftext|等特殊 token得到干净的回复文本。4响应与日志响应体固定为{response: ..., status: 200, time: ...}其中time为请求处理时刻的格式化时间戳。终端会打印[时间] , prompt:..., response:...格式的日志便于服务端观测每次请求的输入输出。5模型加载model_name_or_path指向 2.3 节下载得到的本地模型路径/root/autodl-tmp/phi3/model/LLM-Research/Phi-3-mini-4k-instruct。加载时使用device_mapcuda将模型分配到 GPUtorch_dtypeauto自动采用模型权重自身的精度trust_remote_codeTrue允许执行模型仓库中的自定义代码Phi-3 需要此项。加载完成后调用.eval()切换到推理模式。uvicorn.run(app, host0.0.0.0, port6006, workers1)以单 worker 启动服务监听所有网卡上的 6006 端口。注意因为模型加载在if __name__ __main__块中workers必须保持为 1多 worker 会导致每个进程各自加载一份模型副本并带来端口冲突风险。五、启动服务并验证调用5.1 启动 API 服务在终端中运行cd /root/autodl-tmp python api.py等待模型权重加载完成后服务即监听在 6006 端口默认通过POST 方法进行调用。5.2 使用 curl 调用curl -X POST http://127.0.0.1:6006 \ -H Content-Type: application/json \ -d {prompt: 你好, history: []}典型响应如下{ response: 你好如果你需要帮助或者有任何问题请随时告诉我。, status: 200, time: 2024-05-09 16:36:43 }5.3 使用 Python requests 调用除了 curl也可以写一个简单的 Python 客户端本仓库其他模型的 FastAPI 教程如 InternLM2 FastAPI 部署也采用了完全一致的接口约定可互相参考import requests import json def get_completion(prompt): headers {Content-Type: application/json} data {prompt: prompt, history: []} response requests.post(urlhttp://127.0.0.1:6006, headersheaders, datajson.dumps(data)) return response.json()[response] if __name__ __main__: print(get_completion(你好))六、SSH 端口映射与 Postman 本地访问AutoDL 等云端实例的外部请求通常需要通过 SSH 端口映射才能从本地访问。将服务器 6006 端口映射到本机ssh -CNg -L 6006:127.0.0.1:6006 -p 【你的autodl机器的ssh端口】 root[你的autodl机器地址]其中-p后的端口替换为你的 AutoDL 实例 SSH 端口地址替换为实例的 SSH 域名。一个实际示例请以自己实例的信息为准ssh -CNg -L 6006:127.0.0.1:6006 -p 36494 rootregion-45.autodl.pro映射完成后在本地打开 Postman请求方法选择POSTURL 填写http://127.0.0.1:6006Body 选择raw并设置为JSON类型输入{prompt: 请讲一个故事, history: []}点击发送即可看到模型返回的生成结果。如上图所示服务返回了完整的故事文本以及status: 200和请求处理时间time字段说明 API 服务运行正常。关于 AutoDL 端口映射的通用操作仓库的 AutoDL 开放端口文档 有更详细的说明。七、常见问题与排查要点问题现象排查思路加载模型报KeyError/ 不识别模型类型多为transformers版本过低导致执行pip list \| grep transformers确认版本并按 2.4 节升级到4.41.0.dev0提示 custom code 需要确认加载时务必传trust_remote_codeTrue否则 Phi-3 的自定义代码不会被执行服务启动后外部无法访问确认uvicorn.run的host0.0.0.0并完成第六节的 SSH 端口映射多轮请求后显存持续增长检查每次请求末尾是否执行了torch_gc()必要时可下调max_new_tokens请求返回 500检查请求体是否为合法 JSON且包含prompt字段八、延伸从 FastAPI 走向更完整的应用链路本教程完成的是 模型能力 HTTP 化 这一步。在同一仓库的models/phi-3目录下还提供了基于同一部署环境的后续方案可作为本文的延伸阅读Phi-3-mini-4k-instruct langchain 接入继承langchain.llms.base.LLM自定义Phi3Mini_LLM类并重写_call方法将本地模型无缝接入 LangChain 生态Phi-3-mini-4k-instruct WebDemo 部署基于 Streamlit 构建可视化对话界面其中bulid_input函数手工拼接|user|\n...|end|\n|assistant|\n模板的方式与本文使用的apply_chat_template等效Phi-3-mini-4k-Instruct Lora 微调基于peft对 Phi-3 进行 LoRA 指令微调对应的完整可运行 Notebook 见 Phi-3-mini-4k-Instruct-Lora.ipynb。至此你已经完成了 Phi-3-mini-4k-instruct 的 FastAPI 部署从镜像环境搭建、依赖与 transformers 版本锁定、ModelScope 模型下载到 API 服务的编写、curl/Postman 联调与 SSH 端口映射形成了一条完整、可复现、可继续扩展的本地大模型服务化路径。【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/GitHub_Trending/se/self-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考