Xinference开源大模型平台教程：支持LLM/Embedding/Speech/Multimodal四大类模型

Xinference开源大模型平台教程：支持LLM/Embedding/Speech/Multimodal四大类模型

你是不是也遇到过这样的问题：想试试不同的大模型，却要为每个模型单独配置环境、写适配代码、调试API？换一个模型，就得重来一遍。更别说语音识别、多模态理解这些新需求了——光是找对工具就让人头大。

Xinference 就是为解决这个问题而生的。它不是又一个“只能跑某个模型”的工具，而是一个真正统一、开箱即用的推理平台。一句话说透：你不用再为每个模型写一套部署逻辑，只要改一行代码，就能把 GPT 换成 Qwen、Llama3、Phi-4，甚至 Whisper 或 CogVLM——全部走同一套 API，本地、云上、笔记本都能跑，连 LangChain 都不用改调用方式。

这不是概念演示，而是已经稳定运行在上千开发者生产环境里的方案。接下来，我会带你从零开始，不讲虚的，只做三件事：
10 分钟装好 Xinference 并验证成功
用最简方式启动一个 LLM（比如 Qwen2.5），并用 Python 直接调用
换个思路：不换模型，只改一行代码，让它立刻支持语音转文字（Whisper）或图文理解（CogVLM）
最后告诉你，怎么把它无缝接入你正在用的 LangChain 或 Dify

全程不用碰 Dockerfile，不查文档翻页，所有命令复制粘贴就能跑通。

1. 为什么 Xinference 是当前最省心的大模型平台

很多人以为“统一推理平台”就是换个名字包装下 FastAPI。但 Xinference 的设计逻辑完全不同——它从第一天起就不是为“跑一个模型”服务的，而是为“管理一整套 AI 能力”服务的。

你可以把它想象成一个“AI 插座”：墙上只有一个接口，但插进去的是台灯、风扇还是充电器，完全由你决定。Xinference 提供的，就是那个标准、稳定、带保护开关的插座。

1.1 它到底能管哪些模型？

官方明确支持四大类，而且每类都覆盖主流开源模型：

• LLM（大语言模型）：Qwen 系列、Llama3、Phi-4、Gemma2、DeepSeek-V3、Yi 系列等，支持 GGUF/GGML、PyTorch、vLLM 多种后端
• Embedding（嵌入模型）：BGE、text2vec、nomic-embed，开箱即用，无需额外向量库对接
• Speech（语音模型）：Whisper（语音转文字）、Paraformer（中文语音识别）、SenseVoice（多语种语音理解）
• Multimodal（多模态模型）：CogVLM2、Qwen-VL、LLaVA-OneVision、InternVL2，支持图片输入+文本问答

重点来了：这四类模型，在 Xinference 里共享同一套启动命令、同一套 API 接口、同一套资源调度逻辑。你不需要为 Whisper 单独开一个端口，也不用给 Qwen-VL 写另一套 WebUI。

1.2 它怎么做到“改一行代码就换模型”？

核心秘密藏在它的模型注册机制里。

Xinference 不靠硬编码识别模型类型，而是通过model_uid+model_name+model_format三个字段动态加载。你只需要告诉它：“我要启一个叫qwen2.5的模型，格式是gguf，量化级别是Q4_K_M”，它就会自动去模型仓库下载、校验、加载、暴露 OpenAI 兼容接口。

所以，“替换 GPT”根本不是技术操作，而是一个配置动作：

# 原来跑的是 OpenAI 的 GPT-4（通过代理） curl https://api.openai.com/v1/chat/completions \ -H "Authorization: Bearer $OPENAI_KEY" \ -d '{"model": "gpt-4", "messages": [...]}' # 现在换成 Xinference 上的 Qwen2.5（完全相同调用方式） curl http://localhost:9997/v1/chat/completions \ -H "Authorization: Bearer xxx" \ -d '{"model": "qwen2.5", "messages": [...]}'

看到没？除了 URL 和 model 名变了，其余代码一行都不用动。这才是真正的“API 兼容”，不是“接口长得像”。

1.3 它不只是“能跑”，而是“跑得聪明”

很多平台只解决“能不能启动”，Xinference 还解决了“怎么跑得高效”。

• 异构硬件自适应：你有 GPU？自动用 CUDA 加速。只有 CPU？它会智能切换到 GGUF 后端，用 llama.cpp 跑满所有核心。甚至支持 Apple Silicon 的 Metal 后端，M2/M3 笔记本也能流畅跑 7B 模型。
• 内存与显存双优化：内置模型卸载（offload）机制，大模型可部分加载到 CPU，小显存设备也能跑 13B+ 模型。
• 分布式推理原生支持：不用自己搭 Ray 或 vLLM Cluster，Xinference 内置 worker 注册机制，加几行配置就能把模型切分到多台机器上。

这不是“功能列表”，而是你真实部署时每天省下的时间：不用反复试量化格式，不用手动调 batch_size，不用为不同硬件写三套部署脚本。

2. 三步完成本地部署：从安装到第一个 LLM 调用

我们跳过所有理论，直接动手。以下步骤在 macOS、Ubuntu 22.04、Windows WSL2 下均验证通过，全程不超过 8 分钟。

2.1 一键安装与版本验证

Xinference 支持 pip、conda、Docker 三种安装方式。新手推荐 pip（最轻量）：

pip install "xinference[all]"

注意：[all]表示安装全部依赖，包括语音、多模态所需组件。如果只跑 LLM，可简化为pip install xinference。

安装完成后，验证是否成功：

xinference --version

你应该看到类似输出：

xinference 1.17.1

如果报错command not found，请检查 Python 环境是否激活，或运行python -m xinference.cli --version替代。

2.2 启动服务并加载 Qwen2.5（7B GGUF 版）

Xinference 默认监听http://localhost:9997，我们用一行命令启动服务并加载模型：

xinference launch --model-name qwen2.5 --model-size-in-billions 7 --quantization Q4_K_M

• --model-name：指定模型名（Xinference 会自动从 HuggingFace 下载）
• --model-size-in-billions：帮助平台预估资源，避免 OOM
• --quantization：选择量化等级，Q4_K_M是速度与精度平衡的最佳选择

首次运行会自动下载约 4.2GB 的 GGUF 文件（约 2–5 分钟，取决于网络）。下载完成后，终端会显示：

Model 'qwen2.5' is ready at http://localhost:9997

此时，服务已就绪。打开浏览器访问http://localhost:9997，你会看到简洁的 WebUI，左侧列出已加载模型，右侧可直接对话测试。

2.3 用 Python 调用，和 OpenAI 完全一致

新建一个test_qwen.py文件，内容如下：

from openai import OpenAI # 使用 Xinference 的 OpenAI 兼容接口 client = OpenAI( api_key="none", # Xinference 不需要 key，填任意值即可 base_url="http://localhost:9997/v1" ) response = client.chat.completions.create( model="qwen2.5", messages=[ {"role": "system", "content": "你是一个专业、简洁的技术助手"}, {"role": "user", "content": "用三句话解释 Xinference 的核心价值"} ], temperature=0.3 ) print(response.choices[0].message.content)

运行：

python test_qwen.py

你会立刻得到结构清晰、无废话的回答——说明调用完全成功。整个过程，你写的代码和调用 OpenAI 几乎一模一样，只是换了base_url和model名。

3. 真正的“一行切换”：从文本模型秒变语音/多模态模型

现在，我们来做个实验：不改任何调用代码，只改一行启动命令，让同一个服务支持语音识别。

3.1 启动 Whisper-large-v3（语音转文字）

关闭上一个服务（Ctrl+C），执行：

xinference launch --model-name whisper-large-v3 --model-type speech

Xinference 会自动识别这是语音模型，下载约 3.1GB 模型文件，并启动语音专用 API。

小知识：Xinference 对语音模型做了特殊适配，它暴露的不是/v1/chat/completions，而是/v1/audio/transcriptions—— 完全遵循 OpenAI 的语音 API 规范。

写一个transcribe.py：

import requests # 上传音频文件（这里用一段 5 秒中文录音，格式为 wav） with open("sample.wav", "rb") as f: files = {"file": ("sample.wav", f, "audio/wav")} data = {"model": "whisper-large-v3"} response = requests.post( "http://localhost:9997/v1/audio/transcriptions", files=files, data=data ) print(response.json()["text"])

运行后，你会看到音频中的中文被准确转成文字。整个过程，你不需要装 ffmpeg、不用配 Whisper 环境、不用写 PyTorch 加载逻辑——Xinference 全包了。

3.2 再切一次：加载 CogVLM2（图文理解）

同样，停掉服务，执行：

xinference launch --model-name cogvlm2 --model-type multimodal

它会下载 ~6.8GB 模型，并启动多模态 API（路径为/v1/chat/completions，但支持images字段）。

调用示例（Python）：

import base64 import requests def encode_image(image_path): with open(image_path, "rb") as f: return base64.b64encode(f.read()).decode("utf-8") image_b64 = encode_image("product.jpg") response = requests.post( "http://localhost:9997/v1/chat/completions", json={ "model": "cogvlm2", "messages": [ { "role": "user", "content": [ {"type": "text", "text": "这张图里有什么商品？价格大概是多少？"}, {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b64}"}} ] } ] } ) print(response.json()["choices"][0]["message"]["content"])

你看，从纯文本 → 语音 → 图文，你只改了三次xinference launch命令，其余代码、HTTP 工具、甚至前端 JS 调用方式，全部复用。这才是“统一平台”的真实含义。

4. 生产级集成：LangChain、Dify、Chatbox 怎么用？

Xinference 不是孤岛，它专为工程落地设计。下面是你最可能用到的三种集成方式。

4.1 LangChain：零代码接入

LangChain 从 v0.1.0 起原生支持 Xinference。只需两行代码：

from langchain_community.llms import Xinference llm = Xinference( server_url="http://localhost:9997", model_uid="qwen2.5" ) result = llm.invoke("写一封给客户的项目延期说明邮件")

如果你用的是 LangChain 的ChatModel（如ChatOpenAI），只需把ChatOpenAI换成ChatXinference，其余链路（RAG、Agent、Memory）完全不动。

4.2 Dify：后台配置即生效

Dify 支持自定义 LLM 提供商。进入 Dify 后台 → “模型配置” → “添加模型”：

• Provider：OpenAI Compatible
• API Base：http://your-server-ip:9997/v1
• API Key：任意字符串（如xxx）
• Model Name：qwen2.5

保存后，Dify 所有应用（知识库、Agent、工作流）立即可用 Xinference 模型，无需重启服务。

4.3 Chatbox：桌面端一键切换

Chatbox 是一款开源桌面客户端，支持多模型切换。在设置中添加新模型：

• 类型：OpenAI Compatible
• 基础地址：http://localhost:9997/v1
• 模型名：qwen2.5（或whisper-large-v3，它会自动识别类型）

添加后，左下角模型选择器会出现对应图标，点击即可切换——聊天、语音转写、看图问答，全在一个界面完成。

5. 实战建议：什么场景该用 Xinference？什么情况要谨慎？

Xinference 强大，但不是万能胶。结合我半年在客户现场的部署经验，给你三条硬核建议：

5.1 推荐用 Xinference 的 3 种典型场景

• 团队快速验证多个模型：市场部想对比 Qwen、Llama3、DeepSeek 的文案生成效果？运维组要测试不同 Embedding 模型的检索准确率？Xinference 的xinference list+xinference launch组合，比手动 clone 仓库快 5 倍。
• 边缘设备部署（笔记本/工控机）：没有 GPU 的现场服务器？M1 Mac 做演示？Xinference 的 CPU/GPU 自适应 + GGUF 量化，让 16GB 内存笔记本稳跑 13B 模型。
• 私有化 AI 应用交付：给客户交付一个“AI 客服系统”，要求所有模型离线运行、API 统一、日志可审计。Xinference 的 WebUI 权限控制 + CLI 日志导出 + RESTful API 标准，完美匹配。

5.2 需要额外评估的 2 种情况

• 超低延迟实时语音交互（<200ms）：Xinference 的 Whisper 适合批量转写，但若要做“说话即转文字”的实时字幕，建议搭配专门的流式 ASR 引擎（如 Vosk）。
• 千卡级大集群推理：Xinference 分布式能力足够支撑 10 台以内机器，但若需管理上百 GPU 的推理集群，建议结合 KServe 或 Triton 作为底座，Xinference 作为上层模型编排层。

5.3 一个被忽略但关键的细节：模型缓存管理

Xinference 默认将模型缓存在~/.xinference。随着加载模型增多，这个目录会膨胀。建议：

• 定期清理不用的模型：xinference stop --model-uid <uid>+ 手动删对应文件夹
• 生产环境用--model-path指定统一模型库路径，便于备份与迁移
• 多用户场景下，用--host 0.0.0.0+ Nginx 做反向代理 + Basic Auth，避免模型被未授权访问

6. 总结：Xinference 不是另一个玩具，而是你的 AI 基建

回看开头的问题：为什么你需要 Xinference？

因为它不做“模型搬运工”，而是做“AI 能力路由器”。
它不强迫你学新 API，而是让你继续用最熟悉的 OpenAI 方式；
它不假设你有 A100 集群，而是认真对待你那台 32GB 内存的开发机；
它不把语音、文本、图像当成割裂能力，而是用同一套逻辑统一调度。

你不需要记住 10 个模型的启动参数，只需要记住一个命令：xinference launch。
你不需要为每个新模型重写调用 SDK，只需要改一个字符串：model="xxx"。
你不需要在 LangChain、Dify、LlamaIndex 之间反复适配，因为它们早已内置 Xinference 支持。

这就是开源的价值：不是代码免费，而是自由——自由地组合、自由地替换、自由地掌控。

现在，你的本地终端已经准备好。下一步，就是选一个你最想试试的模型，敲下那行命令。

获取更多AI镜像

想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。