Gemma 4 E4B-it 模型服务部署实战基于 AMD Ryzen AI NPU 的 Lemonade Server 方案【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/datawhalechina/self-llm本篇技术指南聚焦于如何在 Windows 11 的 AMD Ryzen AI 300 系列平台CPU AI 395 / AI 370上通过Lemonade Server一键部署 Gemma 4 E4B-it 的 GGUF 量化模型并将其封装为兼容 OpenAI 协议的标准服务接口。读完本文你将掌握 NPU 环境前置准备、GGUF 权重下载、Lemonade Server 安装与模型加载、以及使用 OpenAI SDK 完成服务联通性测试的完整链路可在本地端侧获得低延迟、OpenAI 兼容的 LLM 服务能力。方案背景为什么在 AMD NPU 平台上用 Lemonade Server 部署 Gemma 4 E4B-itGemma 4 E4B-it 是 Google 开源的多模态指令模型支持文本 / 图像 / 音频输入属小尺寸型号上下文长度达128K在 Hugging Face Transformers 生态中通常使用AutoProcessorAutoModelForMultimodalLM加载详见 01-gemma-4-E4B-it FastApi 部署调用。除了传统 CUDA 显卡方案外AMD Ryzen AI 300 系列处理器凭借内置的XDNA2 架构 NPU可以在不依赖独立显卡的情况下直接在端侧运行中小规模 LLM而Lemonade Server正是面向这一场景的模型服务框架。本仓库在 models/Gemma4 目录下围绕 Gemma 4 E4B-it 提供了从环境准备、微调到服务部署的完整教程族本文对应的服务部署文档8-gemma4-E4B-it 模型服务部署.md与 7-gemma4-E4B-it AMD环境准备 构成前后衔接的两个环节——前者负责把 NPU 驱动、Ryzen AI 软件栈安装到位后者本文则完成模型服务本身的部署与验证。本文采用的核心链路如下GGUF 权重ggml-org/gemma-4-E4B-it-GGUF │ snapshot_download 下载 ▼ Lemonade ServerWindows 端侧模型服务 │ 选择模型启动 ▼ OpenAI 兼容 HTTP 接口http://localhost:8000/api/v1 │ OpenAI SDK 调用 ▼ 本地应用 / Agent / 工具链集成基础环境准备本文部署的基础环境如下---------------- Windows 11 CPU AI 395 内存 128G ----------------注意请先确认 AMD 芯片的具体版本当前方案支持AI 395与AI 370两款芯片。该方案依赖NPU神经处理单元执行推理因此对硬件与驱动有明确要求需要配备AMD Ryzen AI 300 系列的 Windows 11 电脑必须先下载并安装NPU 驱动程序再继续后续操作完整的 NPU 驱动与 Ryzen AI 软件安装步骤、依赖项版本要求Windows 11 build ≥ 22621.3527、Visual Studio 2022、cmake ≥ 3.26、推荐 Miniforge 等以及quicktest.py安装验证方法请严格参照同目录前置文档 7-gemma4-E4B-it AMD环境准备 完成本文不再重复。只有 NPU 环境就绪后Lemonade Server 才能正确识别并调度 NPU 加速器执行模型推理。安装 lemonade-server 与 Python 依赖在 AMD 环境就绪后首先下载并安装lemonade-serverLemonade Server 的官方安装引导界面见下图可选择 Windows 11 平台对应的 Installer 安装包安装完成后打开终端建议使用 Windows PowerShell执行以下命令完成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 -U huggingface_hub pip install lemonade-sdk[dev]其中huggingface_hub用于后续调用snapshot_download下载 GGUF 模型权重lemonade-sdk[dev]Lemonade 的 Python SDK[dev]表示附带开发/调试依赖服务运行时依赖。提示在 PowerShell 中方括号[]具有特殊含义若直接粘贴pip install lemonade-sdk[dev]报错可改用反引号转义[、]或使用cmd执行。下载 Gemma 4 E4B-it GGUF 模型权重配置 Hugging Face 镜像由于网络限制建议在 Windows PowerShell 下配置 Hugging Face 镜像站加速模型仓库下载$env:HF_ENDPOINT https://hf-mirror.com编写下载脚本使用huggingface_hub中的snapshot_download函数下载模型第一个参数为模型名称仓库 ID参数cache_dir为模型的下载路径。新建model_download.py文件粘贴以下内容并保存代码支持通过命令行参数动态指定模型与保存目录#!/usr/bin/env python 使用 Python API 下载 Hugging Face 模型 import os from huggingface_hub import snapshot_download def download_model(repo_id: str, local_dir: str None, resume_download: bool True): 下载 Hugging Face 模型 Args: repo_id: 模型仓库ID例如 ggml-org/gemma-4-E4B-it-GGUF local_dir: 本地保存目录如果为None则使用默认缓存目录 resume_download: 是否支持断点续传 print(f开始下载模型: {repo_id}) print(f保存位置: {local_dir if local_dir else 默认缓存目录}) try: # 如果指定了本地目录使用它否则使用默认缓存 if local_dir: cache_dir os.path.dirname(local_dir) if os.path.dirname(local_dir) else None local_dir_use local_dir else: cache_dir None local_dir_use None # 下载模型 downloaded_path snapshot_download( repo_idrepo_id, local_dirlocal_dir_use, cache_dircache_dir, resume_downloadresume_download, local_files_onlyFalse ) print(f\n✓ 模型下载完成) print(f保存路径: {downloaded_path}) return downloaded_path except Exception as e: print(f\n✗ 下载失败: {str(e)}) raise if __name__ __main__: import sys # 默认下载的模型 repo_id ggml-org/gemma-4-E4B-it-GGUF # 如果提供了命令行参数使用它作为模型ID if len(sys.argv) 1: repo_id sys.argv[1] # 可选指定本地保存目录 local_dir None if len(sys.argv) 2: local_dir sys.argv[2] download_model(repo_id, local_dir)脚本的几个设计要点仓库 ID 可覆盖默认下载ggml-org/gemma-4-E4B-it-GGUF也可通过第一个命令行参数传入其他仓库本地目录可覆盖第二个命令行参数用于指定保存路径断点续传resume_downloadTrue保证下载中断后可继续无需重新开始缓存目录逻辑当指定local_dir时其父目录作为cache_dir传入二者配合避免重复缓存占用磁盘。执行下载在终端中运行以下命令启动下载python model_download.py ggml-org/gemma-4-E4B-it-GGUF C:\Users\aup\.cache\huggingface\hub\gemma-4-E4B-it-GGUF下载完成后本地目录中应包含可供 Lemonade Server 直接加载的 GGUF 权重文件。GGUF 格式是 llama.cpp 生态的量化权重格式体积远小于原始 safetensors 权重非常适合端侧 NPU/CPU 环境部署。支持的硬件加速器Lemonade Server 面向 AMD 平台提供了多层次的硬件加速能力依据部署文档中的加速器说明可归纳如下模式说明NPU Hybrid混合执行面向 Ryzen AI 300 系列设备的 NPU神经处理单元支持 LLM 推理通过混合执行策略——NPU 负责生成首 tokeniGPU 计算剩余 token——显著加速 TTFT首个 token 生成时间兼顾首包延迟与持续吞吐GPU同时支持集成显卡iGPU与独立显卡dGPULemonade Server 通过Vulkan、ROCm、Metal等运行时二进制提供 GPU 加速覆盖 Windows、Linux、macOS 平台注意 CLI 类任务如基准测试暂不支持 GPU 加速对于本教程的 Gemma 4 E4B-it 部署场景NPU Hybrid 模式是发挥 AI 395 / AI 370 芯片 NPU 算力的关键路径这也是前置文档 7-gemma4-E4B-it AMD环境准备 中反复强调必须正确安装 NPU 驱动如版本 32.0.203.280 / 32.0.203.304的原因——NPU 驱动缺失时Hybrid 执行链路无法建立服务将回退或失败。支持的推理引擎Lemonade Server 以引擎Engine为单位对接不同的模型格式与推理后端部署文档中列出的引擎能力对比如下引擎模型格式说明OnnxRuntime GenAI (OGA).onnx微软开发的推理引擎允许硬件厂商提供 EP执行提供器Execution Provider来适配专用硬件如 NPUllamacpp.gguf社区驱动引擎支持 GPU 加速兼容数千个.gguf模型并支持 VLM视觉语言模型与 MoE混合专家等高级特性FastFlowLM.q4nx面向 Ryzen AI 300 系列 NPU 专门优化的引擎支持含 VLM 功能的.q4nx模型目前处于早期访问阶段需商业授权Hugging Face (HF).safetensors使用 PyTorch 运行时加载.safetensors训练权重主要用于提供准确率基准与量化/专用引擎做精度对比由于本文部署的是GGUF 格式的 Gemma 4 E4B-it 权重因此实际加载时会走llamacpp引擎链路若希望进一步榨取 NPU 性能可关注 FastFlowLM 引擎及其.q4nx格式的后续支持情况需注意其授权要求。启动模型服务完成模型下载后通过系统菜单启动Lemonade Server在菜单栏中输入 Lemonade Server 并启动点击菜单中对应的图标见下图左侧的 App 管理菜单可进行 Load Model、Port、Context Size 等设置服务启动后在模型管理界面中选中对应的模型即刚下载的gemma-4-E4B-it-GGUF即可启动推理。模型加载成功后Lemonade Server 会对外输出兼容 OpenAI 的服务接口。从上图服务日志可见服务端已就绪并开始响应/api/v1/models、/api/v1/health等 API 请求HTTP 200同时右侧聊天面板可直接进行人机对话验证。结合下文测试代码中使用的http://localhost:8000/api/v1地址可以看出Lemonade Server 默认监听本机8000端口其 API 路径前缀为/api/v1遵循 OpenAI 的/v1兼容约定。服务测试使用 OpenAI SDK 发起对话请求服务启动后即可通过标准 OpenAI 客户端库进行调用。新建test.py文件并粘贴以下内容代码包含详细注释# Client library provided by OpenAI to automate request # and response processing with the server from openai import OpenAI # The base_url points to an LLM server, which can either be # local (localhost address) or cloud-based (web address) base_url fhttp://localhost:8000/api/v1 # The client instance here provides APIs to request # LLM invocations from the server client OpenAI( base_urlbase_url, api_keylemonade, # required, but unused in Lemonade ) # The messages list provides the history of messages from # the system, assistant, and user roles messages [ {role:system, content:You are a helpful assistant.}, {role:user, content:Hi, how are you?}, ] # This is the API call that sends the messages history to # the servers specific LLM model # It returns a completion, which is OpenAIs way of referring # to the LLMs reponse to the messages completion client.chat.completions.create( modelgemma-4-E4B-it-GGUF, messagesmessages, ) # This code gets the LLMs response from the completion # and prints it to the screen response completion.choices[0].message.content print(response)要点说明base_url指向本地 Lemonade Server 的 OpenAI 兼容端点http://localhost:8000/api/v1若服务部署在远端则替换为对应地址api_keyLemonade 要求该字段存在但不校验其值可任意填写示例中为lemonademodel必须与服务端加载的模型 ID 一致即gemma-4-E4B-it-GGUFmessages遵循 OpenAI 的 system / user / assistant 多轮消息结构。运行python test.py返回结果如下模型已正确响应提问并给出流畅回复这一结果同时验证了两件事其一GGUF 权重已被 llamacpp 引擎正确加载并执行推理其二OpenAI 兼容的 HTTP 服务链路/api/v1/chat/completions完全打通可直接被 LangChain、各类 Agent 框架或自研应用当作标准 LLM 后端接入。仓库源码佐证两条部署路径的互补关系本仓库在 models/Gemma4 目录下为 Gemma 4 E4B-it 同时维护了两种服务化路径可从源码层面交叉印证本文方案本文方案Windows NPU Lemonade Server面向端侧 NPU 场景通过 Lemonade 的引擎抽象层完成 GGUF 权重的服务化适合无独立显卡的 Ryzen AI 笔记本/迷你主机仓库内 api.py 01-gemma-4-E4B-it FastApi 部署调用Linux CUDA FastAPI面向云端 GPU 场景直接以AutoModelForMultimodalLMAutoProcessor加载原始 safetensors 权重并通过/chat/completions路由暴露服务支持文本与图片URL / base64混合输入。两条路径都以 OpenAI 兼容的消息结构为对外契约区别仅在于推理后端前者交给 Lemonade 的引擎调度NPU/GPU后者直接由 Transformers 在 CUDA 上执行。选择哪条路径取决于你的硬件有 Ryzen AI NPU 的 Windows 设备走本文方案有 NVIDIA GPU 的 Linux 服务器走 FastAPI 方案。此外仓库中的 verify_gemma4_tutorials.py 提供了针对 Gemma4 教程族的冒烟测试其中test_fastapi_smoke_with_mock用 Mock 模型验证了/chat/completions路由的请求/响应契约messages校验、max_new_tokens范围、response/status/tokens_generated等返回字段test_imports则核验了transformers、torch等关键依赖的可用性——这些测试为教程中的代码片段提供了可复现的验证入口也说明本文涉及的服务化接口设计是经过仓库层面检验的。常见问题与排查思路依据前文依赖与仓库文档信息可归纳以下常见问题定位思路现象排查方向Lemonade Server 无法识别模型 / 加载失败确认 NPU 驱动已正确安装任务管理器 → 性能 → NPU0 可见并按 7-gemma4-E4B-it AMD环境准备 执行quicktest.py验证 Ryzen AI 软件栈模型下载缓慢或失败确认已在 PowerShell 中设置$env:HF_ENDPOINT https://hf-mirror.com镜像snapshot_download默认支持断点续传可重试pip install lemonade-sdk[dev]报语法错误PowerShell 中方括号需转义[dev]或改用 cmd 执行测试脚本连接失败确认 Lemonade Server 已启动且模型已加载服务日志中/api/v1/health返回 200确认base_url的端口与服务实际监听端口一致默认 8000需要更高 NPU 性能关注 FastFlowLM 引擎对.q4nx格式的支持需商业授权或调整 Lemonade Server 菜单中的 Context Size 等参数综上本文给出的环境准备 → 安装 → 下载 GGUF → 启动服务 → OpenAI 兼容测试五步链路是 AMD Ryzen AI 300 系列端侧设备上部署 Gemma 4 E4B-it 的标准路径结合仓库内 api.py 与 verify_gemma4_tutorials.py 等源码读者可进一步将本方案的服务契约复用到其他推理后端实现一套 OpenAI 兼容接口、多种硬件后端的灵活架构。【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/datawhalechina/self-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Gemma 4 E4B-it 模型服务部署实战：基于 AMD Ryzen AI NPU 的 Lemonade Server 方案
Gemma 4 E4B-it 模型服务部署实战基于 AMD Ryzen AI NPU 的 Lemonade Server 方案【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/datawhalechina/self-llm本篇技术指南聚焦于如何在 Windows 11 的 AMD Ryzen AI 300 系列平台CPU AI 395 / AI 370上通过Lemonade Server一键部署 Gemma 4 E4B-it 的 GGUF 量化模型并将其封装为兼容 OpenAI 协议的标准服务接口。读完本文你将掌握 NPU 环境前置准备、GGUF 权重下载、Lemonade Server 安装与模型加载、以及使用 OpenAI SDK 完成服务联通性测试的完整链路可在本地端侧获得低延迟、OpenAI 兼容的 LLM 服务能力。方案背景为什么在 AMD NPU 平台上用 Lemonade Server 部署 Gemma 4 E4B-itGemma 4 E4B-it 是 Google 开源的多模态指令模型支持文本 / 图像 / 音频输入属小尺寸型号上下文长度达128K在 Hugging Face Transformers 生态中通常使用AutoProcessorAutoModelForMultimodalLM加载详见 01-gemma-4-E4B-it FastApi 部署调用。除了传统 CUDA 显卡方案外AMD Ryzen AI 300 系列处理器凭借内置的XDNA2 架构 NPU可以在不依赖独立显卡的情况下直接在端侧运行中小规模 LLM而Lemonade Server正是面向这一场景的模型服务框架。本仓库在 models/Gemma4 目录下围绕 Gemma 4 E4B-it 提供了从环境准备、微调到服务部署的完整教程族本文对应的服务部署文档8-gemma4-E4B-it 模型服务部署.md与 7-gemma4-E4B-it AMD环境准备 构成前后衔接的两个环节——前者负责把 NPU 驱动、Ryzen AI 软件栈安装到位后者本文则完成模型服务本身的部署与验证。本文采用的核心链路如下GGUF 权重ggml-org/gemma-4-E4B-it-GGUF │ snapshot_download 下载 ▼ Lemonade ServerWindows 端侧模型服务 │ 选择模型启动 ▼ OpenAI 兼容 HTTP 接口http://localhost:8000/api/v1 │ OpenAI SDK 调用 ▼ 本地应用 / Agent / 工具链集成基础环境准备本文部署的基础环境如下---------------- Windows 11 CPU AI 395 内存 128G ----------------注意请先确认 AMD 芯片的具体版本当前方案支持AI 395与AI 370两款芯片。该方案依赖NPU神经处理单元执行推理因此对硬件与驱动有明确要求需要配备AMD Ryzen AI 300 系列的 Windows 11 电脑必须先下载并安装NPU 驱动程序再继续后续操作完整的 NPU 驱动与 Ryzen AI 软件安装步骤、依赖项版本要求Windows 11 build ≥ 22621.3527、Visual Studio 2022、cmake ≥ 3.26、推荐 Miniforge 等以及quicktest.py安装验证方法请严格参照同目录前置文档 7-gemma4-E4B-it AMD环境准备 完成本文不再重复。只有 NPU 环境就绪后Lemonade Server 才能正确识别并调度 NPU 加速器执行模型推理。安装 lemonade-server 与 Python 依赖在 AMD 环境就绪后首先下载并安装lemonade-serverLemonade Server 的官方安装引导界面见下图可选择 Windows 11 平台对应的 Installer 安装包安装完成后打开终端建议使用 Windows PowerShell执行以下命令完成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 -U huggingface_hub pip install lemonade-sdk[dev]其中huggingface_hub用于后续调用snapshot_download下载 GGUF 模型权重lemonade-sdk[dev]Lemonade 的 Python SDK[dev]表示附带开发/调试依赖服务运行时依赖。提示在 PowerShell 中方括号[]具有特殊含义若直接粘贴pip install lemonade-sdk[dev]报错可改用反引号转义[、]或使用cmd执行。下载 Gemma 4 E4B-it GGUF 模型权重配置 Hugging Face 镜像由于网络限制建议在 Windows PowerShell 下配置 Hugging Face 镜像站加速模型仓库下载$env:HF_ENDPOINT https://hf-mirror.com编写下载脚本使用huggingface_hub中的snapshot_download函数下载模型第一个参数为模型名称仓库 ID参数cache_dir为模型的下载路径。新建model_download.py文件粘贴以下内容并保存代码支持通过命令行参数动态指定模型与保存目录#!/usr/bin/env python 使用 Python API 下载 Hugging Face 模型 import os from huggingface_hub import snapshot_download def download_model(repo_id: str, local_dir: str None, resume_download: bool True): 下载 Hugging Face 模型 Args: repo_id: 模型仓库ID例如 ggml-org/gemma-4-E4B-it-GGUF local_dir: 本地保存目录如果为None则使用默认缓存目录 resume_download: 是否支持断点续传 print(f开始下载模型: {repo_id}) print(f保存位置: {local_dir if local_dir else 默认缓存目录}) try: # 如果指定了本地目录使用它否则使用默认缓存 if local_dir: cache_dir os.path.dirname(local_dir) if os.path.dirname(local_dir) else None local_dir_use local_dir else: cache_dir None local_dir_use None # 下载模型 downloaded_path snapshot_download( repo_idrepo_id, local_dirlocal_dir_use, cache_dircache_dir, resume_downloadresume_download, local_files_onlyFalse ) print(f\n✓ 模型下载完成) print(f保存路径: {downloaded_path}) return downloaded_path except Exception as e: print(f\n✗ 下载失败: {str(e)}) raise if __name__ __main__: import sys # 默认下载的模型 repo_id ggml-org/gemma-4-E4B-it-GGUF # 如果提供了命令行参数使用它作为模型ID if len(sys.argv) 1: repo_id sys.argv[1] # 可选指定本地保存目录 local_dir None if len(sys.argv) 2: local_dir sys.argv[2] download_model(repo_id, local_dir)脚本的几个设计要点仓库 ID 可覆盖默认下载ggml-org/gemma-4-E4B-it-GGUF也可通过第一个命令行参数传入其他仓库本地目录可覆盖第二个命令行参数用于指定保存路径断点续传resume_downloadTrue保证下载中断后可继续无需重新开始缓存目录逻辑当指定local_dir时其父目录作为cache_dir传入二者配合避免重复缓存占用磁盘。执行下载在终端中运行以下命令启动下载python model_download.py ggml-org/gemma-4-E4B-it-GGUF C:\Users\aup\.cache\huggingface\hub\gemma-4-E4B-it-GGUF下载完成后本地目录中应包含可供 Lemonade Server 直接加载的 GGUF 权重文件。GGUF 格式是 llama.cpp 生态的量化权重格式体积远小于原始 safetensors 权重非常适合端侧 NPU/CPU 环境部署。支持的硬件加速器Lemonade Server 面向 AMD 平台提供了多层次的硬件加速能力依据部署文档中的加速器说明可归纳如下模式说明NPU Hybrid混合执行面向 Ryzen AI 300 系列设备的 NPU神经处理单元支持 LLM 推理通过混合执行策略——NPU 负责生成首 tokeniGPU 计算剩余 token——显著加速 TTFT首个 token 生成时间兼顾首包延迟与持续吞吐GPU同时支持集成显卡iGPU与独立显卡dGPULemonade Server 通过Vulkan、ROCm、Metal等运行时二进制提供 GPU 加速覆盖 Windows、Linux、macOS 平台注意 CLI 类任务如基准测试暂不支持 GPU 加速对于本教程的 Gemma 4 E4B-it 部署场景NPU Hybrid 模式是发挥 AI 395 / AI 370 芯片 NPU 算力的关键路径这也是前置文档 7-gemma4-E4B-it AMD环境准备 中反复强调必须正确安装 NPU 驱动如版本 32.0.203.280 / 32.0.203.304的原因——NPU 驱动缺失时Hybrid 执行链路无法建立服务将回退或失败。支持的推理引擎Lemonade Server 以引擎Engine为单位对接不同的模型格式与推理后端部署文档中列出的引擎能力对比如下引擎模型格式说明OnnxRuntime GenAI (OGA).onnx微软开发的推理引擎允许硬件厂商提供 EP执行提供器Execution Provider来适配专用硬件如 NPUllamacpp.gguf社区驱动引擎支持 GPU 加速兼容数千个.gguf模型并支持 VLM视觉语言模型与 MoE混合专家等高级特性FastFlowLM.q4nx面向 Ryzen AI 300 系列 NPU 专门优化的引擎支持含 VLM 功能的.q4nx模型目前处于早期访问阶段需商业授权Hugging Face (HF).safetensors使用 PyTorch 运行时加载.safetensors训练权重主要用于提供准确率基准与量化/专用引擎做精度对比由于本文部署的是GGUF 格式的 Gemma 4 E4B-it 权重因此实际加载时会走llamacpp引擎链路若希望进一步榨取 NPU 性能可关注 FastFlowLM 引擎及其.q4nx格式的后续支持情况需注意其授权要求。启动模型服务完成模型下载后通过系统菜单启动Lemonade Server在菜单栏中输入 Lemonade Server 并启动点击菜单中对应的图标见下图左侧的 App 管理菜单可进行 Load Model、Port、Context Size 等设置服务启动后在模型管理界面中选中对应的模型即刚下载的gemma-4-E4B-it-GGUF即可启动推理。模型加载成功后Lemonade Server 会对外输出兼容 OpenAI 的服务接口。从上图服务日志可见服务端已就绪并开始响应/api/v1/models、/api/v1/health等 API 请求HTTP 200同时右侧聊天面板可直接进行人机对话验证。结合下文测试代码中使用的http://localhost:8000/api/v1地址可以看出Lemonade Server 默认监听本机8000端口其 API 路径前缀为/api/v1遵循 OpenAI 的/v1兼容约定。服务测试使用 OpenAI SDK 发起对话请求服务启动后即可通过标准 OpenAI 客户端库进行调用。新建test.py文件并粘贴以下内容代码包含详细注释# Client library provided by OpenAI to automate request # and response processing with the server from openai import OpenAI # The base_url points to an LLM server, which can either be # local (localhost address) or cloud-based (web address) base_url fhttp://localhost:8000/api/v1 # The client instance here provides APIs to request # LLM invocations from the server client OpenAI( base_urlbase_url, api_keylemonade, # required, but unused in Lemonade ) # The messages list provides the history of messages from # the system, assistant, and user roles messages [ {role:system, content:You are a helpful assistant.}, {role:user, content:Hi, how are you?}, ] # This is the API call that sends the messages history to # the servers specific LLM model # It returns a completion, which is OpenAIs way of referring # to the LLMs reponse to the messages completion client.chat.completions.create( modelgemma-4-E4B-it-GGUF, messagesmessages, ) # This code gets the LLMs response from the completion # and prints it to the screen response completion.choices[0].message.content print(response)要点说明base_url指向本地 Lemonade Server 的 OpenAI 兼容端点http://localhost:8000/api/v1若服务部署在远端则替换为对应地址api_keyLemonade 要求该字段存在但不校验其值可任意填写示例中为lemonademodel必须与服务端加载的模型 ID 一致即gemma-4-E4B-it-GGUFmessages遵循 OpenAI 的 system / user / assistant 多轮消息结构。运行python test.py返回结果如下模型已正确响应提问并给出流畅回复这一结果同时验证了两件事其一GGUF 权重已被 llamacpp 引擎正确加载并执行推理其二OpenAI 兼容的 HTTP 服务链路/api/v1/chat/completions完全打通可直接被 LangChain、各类 Agent 框架或自研应用当作标准 LLM 后端接入。仓库源码佐证两条部署路径的互补关系本仓库在 models/Gemma4 目录下为 Gemma 4 E4B-it 同时维护了两种服务化路径可从源码层面交叉印证本文方案本文方案Windows NPU Lemonade Server面向端侧 NPU 场景通过 Lemonade 的引擎抽象层完成 GGUF 权重的服务化适合无独立显卡的 Ryzen AI 笔记本/迷你主机仓库内 api.py 01-gemma-4-E4B-it FastApi 部署调用Linux CUDA FastAPI面向云端 GPU 场景直接以AutoModelForMultimodalLMAutoProcessor加载原始 safetensors 权重并通过/chat/completions路由暴露服务支持文本与图片URL / base64混合输入。两条路径都以 OpenAI 兼容的消息结构为对外契约区别仅在于推理后端前者交给 Lemonade 的引擎调度NPU/GPU后者直接由 Transformers 在 CUDA 上执行。选择哪条路径取决于你的硬件有 Ryzen AI NPU 的 Windows 设备走本文方案有 NVIDIA GPU 的 Linux 服务器走 FastAPI 方案。此外仓库中的 verify_gemma4_tutorials.py 提供了针对 Gemma4 教程族的冒烟测试其中test_fastapi_smoke_with_mock用 Mock 模型验证了/chat/completions路由的请求/响应契约messages校验、max_new_tokens范围、response/status/tokens_generated等返回字段test_imports则核验了transformers、torch等关键依赖的可用性——这些测试为教程中的代码片段提供了可复现的验证入口也说明本文涉及的服务化接口设计是经过仓库层面检验的。常见问题与排查思路依据前文依赖与仓库文档信息可归纳以下常见问题定位思路现象排查方向Lemonade Server 无法识别模型 / 加载失败确认 NPU 驱动已正确安装任务管理器 → 性能 → NPU0 可见并按 7-gemma4-E4B-it AMD环境准备 执行quicktest.py验证 Ryzen AI 软件栈模型下载缓慢或失败确认已在 PowerShell 中设置$env:HF_ENDPOINT https://hf-mirror.com镜像snapshot_download默认支持断点续传可重试pip install lemonade-sdk[dev]报语法错误PowerShell 中方括号需转义[dev]或改用 cmd 执行测试脚本连接失败确认 Lemonade Server 已启动且模型已加载服务日志中/api/v1/health返回 200确认base_url的端口与服务实际监听端口一致默认 8000需要更高 NPU 性能关注 FastFlowLM 引擎对.q4nx格式的支持需商业授权或调整 Lemonade Server 菜单中的 Context Size 等参数综上本文给出的环境准备 → 安装 → 下载 GGUF → 启动服务 → OpenAI 兼容测试五步链路是 AMD Ryzen AI 300 系列端侧设备上部署 Gemma 4 E4B-it 的标准路径结合仓库内 api.py 与 verify_gemma4_tutorials.py 等源码读者可进一步将本方案的服务契约复用到其他推理后端实现一套 OpenAI 兼容接口、多种硬件后端的灵活架构。【免费下载链接】self-llm《开源大模型食用指南》针对中国宝宝量身打造的基于Linux环境快速微调全参数/Lora、部署国内外开源大模型LLM/多模态大模型MLLM教程项目地址: https://gitcode.com/datawhalechina/self-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考