Xinference-v1.17.1快速上手：5分钟启动WebUI，OpenAI兼容API调用代码实例
Xinference-v1.17.1快速上手：5分钟启动WebUI，OpenAI兼容API调用代码实例
1. 为什么你需要Xinference——一个真正开箱即用的模型服务平台
你有没有试过为跑一个开源大模型，花两小时配环境、改配置、查报错，最后发现显存不够？或者刚部署好API，却发现前端调用时格式不兼容，又要重写请求逻辑？
Xinference-v1.17.1 就是来终结这些麻烦的。
它不是另一个需要你从源码编译、手动注册模型、逐个调试端口的推理框架。它是一个“装完就能用、改一行就换模型、打开浏览器就有界面、发个HTTP请求就能调”的生产级推理平台。最新版v1.17.1在稳定性、WebUI响应速度和OpenAI API兼容性上做了显著优化——比如WebUI加载时间缩短40%，函数调用（function calling）的参数解析更鲁棒，对Qwen2、Phi-3、Gemma-2等新模型的默认支持开箱即得。
更重要的是，它不绑架你。你不需要为了用Llama-3而去学一套新协议，也不必为了接入LangChain而重写整个链路。Xinference把所有复杂性藏在背后，只留给你两个最自然的入口：一个图形界面，和一个你早已熟悉的OpenAI风格API。
这就像给AI模型装上了USB-C接口——插上就能供电，拔掉就能换设备，不用再找转接头、查电压、测电流。
2. 5分钟完成本地启动：从安装到WebUI可用
别被“推理平台”四个字吓住。Xinference的安装和启动，比装一个VS Code扩展还简单。全程无需conda环境、不强制Docker、不依赖特定Python版本——只要你的机器有Python 3.9+，就能跑起来。
2.1 一行命令安装（含GPU加速支持）
打开终端（macOS/Linux）或命令提示符（Windows），执行：
pip install "xinference[all]" 这个[all]是关键：它会自动安装GPU推理所需的vLLM（CUDA版）、CPU量化推理的llama-cpp-python、以及WebUI依赖的gradio和fastapi。如果你确定只用CPU，可以换成pip install "xinference[cpu]"，安装体积小60%，启动更快。
验证安装是否成功
运行以下命令，看到版本号即表示安装完成：
2.2 启动服务：默认端口，零配置
继续在终端中输入：
xinference-local 你会立刻看到类似这样的输出：
Xinference server is running at: http://127.0.0.1:9997 Web UI is available at: http://127.0.0.1:9997/ui OpenAI-compatible API endpoint: http://127.0.0.1:9997/v1 没错——不需要改config.yaml，不需要指定模型路径，不需要等待模型下载。xinference-local会自动拉起一个轻量级服务，监听本地9997端口，并内置一个精简但功能完整的WebUI。
现在，打开浏览器，访问 http://127.0.0.1:9997/ui，你将看到一个干净的界面：左侧是模型列表（初始为空），右侧是聊天窗口，顶部有“启动模型”按钮。整个过程，从敲下回车到看到UI，通常不超过90秒。
2.3 在WebUI中启动第一个模型：三步操作
- 点击右上角 “Launch Model” 按钮
- 在弹出窗口中，保持默认选项：
- Model Format：
pytorch（适合大多数LLM） - Model Size：
medium（自动选7B级别，兼顾速度与效果） - Quantization：
none（首次体验建议不量化，保证效果）
- Model Format：
- 点击 “Launch” ——Xinference会自动从Hugging Face下载Qwen2-1.5B-Instruct（v1.17.1默认推荐模型），并在2分钟内完成加载。
加载完成后，模型出现在左侧列表，点击它，右侧聊天框即可开始对话。试试输入：“用一句话解释量子纠缠”，你会得到一个准确、简洁、无幻觉的回答——这不是演示，这就是你本地正在运行的真实推理能力。
3. OpenAI兼容API：用你熟悉的代码，调用任何模型
Xinference最强大的设计，是它把“模型切换”这件事，降维成一次API参数修改。你不需要重写业务逻辑，不需要适配新SDK，只需要改一行代码——把model="gpt-3.5-turbo"换成model="qwen2"，其余全部照旧。
3.1 请求结构完全一致：零学习成本
Xinference的/v1/chat/completions端点，严格遵循OpenAI API规范。这意味着，你过去写的这段代码：
import openai client = openai.OpenAI( base_url="http://127.0.0.1:9997/v1", api_key="not-needed" # Xinference不校验key，填任意字符串即可 ) response = client.chat.completions.create( model="qwen2", # ← 这里就是唯一要改的地方！ messages=[ {"role": "user", "content": "请用中文写一首关于春天的五言绝句"} ], temperature=0.7 ) print(response.choices[0].message.content) 运行结果会是：
春风拂柳绿，燕语绕花飞。 桃李争新艳，山河换翠微。 注意三个关键点：
base_url指向你的本地Xinference服务（不是https://api.openai.com）api_key可填任意非空字符串（如"x"），Xinference默认跳过鉴权model参数值直接使用Xinference中的模型UID（如qwen2、phi3、gemma2），不是Hugging Face ID
3.2 支持完整OpenAI功能集：不只是基础聊天
Xinference不仅支持chat/completions，还完整实现了以下OpenAI核心能力，开箱即用：
| 功能 | 是否支持 | 使用说明 |
|---|---|---|
| Function Calling | 在tools字段传入函数定义，Xinference自动解析参数并返回tool_calls | |
| Streaming | 设置stream=True，获得SSE流式响应，前端可实现打字机效果 | |
| JSON Mode | 添加response_format={"type": "json_object"}，强制模型输出合法JSON | |
| Embeddings | 调用/v1/embeddings，支持bge-m3、nomic-embed-text等主流嵌入模型 | |
| Moderation | /v1/moderations接口可用于内容安全过滤 |
举个函数调用的实际例子——让模型帮你查天气：
tools = [{ "type": "function", "function": { "name": "get_current_weather", "description": "获取指定城市的当前天气", "parameters": { "type": "object", "properties": { "location": {"type": "string", "description": "城市名称，如北京、上海"}, "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]} }, "required": ["location"] } } }] response = client.chat.completions.create( model="qwen2", messages=[{"role": "user", "content": "上海今天多少度？"}], tools=tools, tool_choice="auto" ) # 输出中会包含 tool_calls 字段，例如： # {"name": "get_current_weather", "arguments": '{"location": "上海", "unit": "celsius"}'} 你不需要自己写函数解析器——Xinference已内置，返回结构化数据，你只需按OpenAI文档方式处理即可。
4. 模型热切换：一行代码，从Qwen2换成Phi-3
这才是Xinference区别于其他工具的核心价值：模型不是部署时绑定的，而是运行时可选的资源。
你不需要重启服务、不需要停掉当前模型、不需要清空显存。只要模型已下载（或首次调用时自动下载），就可以在任意时刻切换。
4.1 查看当前可用模型列表
通过API获取所有已注册模型（包括未启动的）：
curl http://127.0.0.1:9997/v1/models 响应中会列出类似：
{ "object": "list", "data": [ { "id": "qwen2", "object": "model", "created": 1715823401, "owned_by": "xinference", "type": "LLM" }, { "id": "phi3", "object": "model", "created": 1715823402, "owned_by": "xinference", "type": "LLM" } ] } 4.2 启动新模型：一条命令，无需等待
想立刻试试Phi-3？不用退出服务，新开一个终端，执行：
xinference launch --model-name phi3 --size medium 几秒钟后，phi3就会出现在/v1/models列表中。此时，你只需把之前Python代码里的model="qwen2"改成model="phi3"，重新运行——请求就自动路由到新模型。
小技巧：Xinference支持多模型并行加载。你可以同时运行qwen2处理长文本摘要，phi3处理实时对话，bge-m3做向量检索——全部共享同一套API网关，无需维护多个服务实例。
5. 实战场景：用Xinference搭建一个本地AI助手
光说不练假把式。我们用一个真实需求收尾：为公司内部知识库搭建一个无需联网、不传数据的问答助手。
5.1 场景拆解与技术选型
| 需求 | Xinference方案 | 说明 |
|---|---|---|
| 数据不出内网 | 全本地部署 | 模型、向量库、API服务均运行在员工笔记本或内网服务器 |
| 支持文档解析 | 集成unstructured + bge-m3 | Xinference内置嵌入模型，配合LangChain可直接处理PDF/Word |
| 响应快、不卡顿 | phi3（4B）+ CPU量化 | 在MacBook M2上，单次问答平均延迟<1.2秒 |
| 对接现有系统 | OpenAI API兼容 | 前端/后端代码0修改，仅改base_url和model名 |
5.2 三步完成搭建（含可运行代码）
第一步：启动嵌入模型与LLM
# 启动嵌入模型（用于知识库向量化） xinference launch --model-name bge-m3 --model-format pytorch # 启动轻量LLM（用于生成答案） xinference launch --model-name phi3 --size small --quantization q4_k_m 第二步：用LangChain连接Xinference（Python脚本）
from langchain_community.llms import Xinference from langchain_community.embeddings import XinferenceEmbeddings from langchain_chroma import Chroma from langchain_core.documents import Document # 连接本地Xinference llm = Xinference( server_url="http://127.0.0.1:9997", model_uid="phi3", # ← 切换模型只需改这里 max_tokens=512 ) embeddings = XinferenceEmbeddings( server_url="http://127.0.0.1:9997", model_uid="bge-m3" ) # 构建知识库（示例：3条公司政策） docs = [ Document(page_content="员工请假需提前3天提交OA申请，病假需附医院证明。"), Document(page_content="报销发票必须为国家税务局监制，抬头为公司全称。"), Document(page_content="远程办公需每日9:00前打卡，周报周五18:00前提交。") ] vectorstore = Chroma.from_documents(docs, embeddings) # QA链 from langchain.chains import RetrievalQA qa_chain = RetrievalQA.from_chain_type( llm=llm, retriever=vectorstore.as_retriever(), return_source_documents=True ) # 提问 result = qa_chain.invoke({"query": "我生病了怎么请假？"}) print(result["result"]) # 输出：您需要提前3天提交OA请假申请，并附上医院开具的病假证明。 第三步：部署为Web服务（FastAPI示例）
from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class QueryRequest(BaseModel): question: str @app.post("/ask") def ask_question(req: QueryRequest): result = qa_chain.invoke({"query": req.question}) return {"answer": result["result"], "sources": [d.metadata for d in result["source_documents"]]} 启动：uvicorn main:app --host 0.0.0.0 --port 8000
调用：curl -X POST http://localhost:8000/ask -H "Content-Type: application/json" -d '{"question":"报销要什么发票？"}'
整个流程，没有一行代码涉及模型加载、CUDA配置或API协议转换。你专注业务逻辑，Xinference负责把一切连通。
6. 总结：Xinference不是另一个工具，而是你的AI基础设施底座
回顾这5分钟的上手之旅，你实际完成了三件过去需要半天才能搞定的事：
- 启动一个带WebUI的生产级推理服务
- 用标准OpenAI代码调用本地大模型
- 在不中断服务的前提下，随时切换不同架构、不同尺寸的模型
Xinference v1.17.1 的价值，不在于它支持了多少种模型，而在于它消除了模型与应用之间的摩擦层。你不再需要为每个新模型学习一套新API，不再需要为每次升级重写集成代码，不再需要在“能跑”和“跑得稳”之间反复权衡。
它让你回归开发者最本真的状态：思考问题，写逻辑，交付价值。模型只是你调用的一个函数，API只是你发送的一次请求，而Xinference，就是那个永远在线、从不掉链子的可靠伙伴。
现在，关掉这篇教程，打开你的终端——输入xinference-local，然后试着把model="qwen2"改成model="gemma2"。你会发现，通往AI应用的大门，原来一直开着，只是你以前没找到那把最简单的钥匙。
获取更多AI镜像
想探索更多AI镜像和应用场景？访问 ZEEKLOG星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
