如何在 Jupyter Notebook 中使用 Xinference v1.17.1 部署开源模型。内容包括环境安装、本地服务启动、以及加载 Qwen、Llama3 文本模型和 Whisper 语音识别模型的具体步骤。教程展示了如何通过 Python API 进行模型交互、多轮对话、语音转录，并提供了 OpenAI 兼容接口的调用示例。此外，还涵盖了模型管理、终止及资源优化等高级技巧，帮助用户实现本地化、低成本的 AI 推理服务。
Xinference 是一个开源的一站式模型推理和服务平台。它把各种开源模型的部署、运行和调用都标准化、简单化了。
主要解决的痛点包括：
而 Xinference 通过一个统一的命令行和 Python API，把这些问题都打包解决了。它的核心特点是'一个命令启动模型，一行代码切换模型'。
我们的目标是在 Jupyter Notebook 中交互，所以安装过程也在 Jupyter 中进行。
打开你的 Jupyter Notebook，在一个新的代码单元格中，执行以下命令来安装 Xinference。这里我们指定安装 1.17.1 版本。
!pip install -U "xinference[all]==1.17.1"
参数解释：
-U：确保升级到最新版本。xinference[all]：安装 Xinference 及其所有额外依赖（包括 GPU 支持、Web UI 等）。如果你只需要基础功能，可以只安装 xinference。==1.17.1：指定安装版本，确保和本教程一致。安装过程可能会持续几分钟，因为它会下载并安装一些较大的依赖包。
安装完成后，我们可以通过 Python 来验证，也可以检查命令行工具。
方法一：在 Notebook 中验证
import xinference print(f"Xinference 版本：{xinference.__version__}")
如果成功输出版本号 1.17.1，说明核心库安装成功。
方法二：使用命令行验证（在 Notebook 中）
!xinference --version
同样，你应该能看到版本号信息。
Xinference 采用客户端 - 服务器架构。我们需要先启动一个本地推理服务（Server），然后通过客户端（Client）去连接并管理模型。
在 Jupyter 中，我们可以在一个独立的代码单元格里启动服务。为了不影响后续交互，我们通常会在后台启动它，或者另起一个终端。但在 Notebook 里演示，我们可以先在前台启动，观察日志。
from xinference.local import start_local_cluster # 启动一个本地集群（包含一个 worker） # endpoint 参数指定服务地址，默认是 http://127.0.0.1:9997 # 我们也可以指定其他端口，比如 9998，避免冲突 cluster = start_local_cluster(endpoint="http://127.0.0.1:9998") print(f"Xinference 服务已启动在：{cluster.endpoint}")
运行这段代码，你会看到一系列日志输出，最后显示服务地址。请记住这个地址（http://127.0.0.1:9998），后续客户端连接需要用到。
重要提示：在 Jupyter 中直接运行上述代码会阻塞当前单元格。对于长期运行的服务，更推荐在终端中启动：
xinference local -H 127.0.0.1 -p 9998
然后让它在后台运行。在本教程中，为了流程连贯，我们假设服务已在 http://127.0.0.1:9998 运行。
服务启动后，在另一个单元格中，我们创建客户端来连接它。
from xinference.client import Client # 创建客户端，指向我们启动的服务地址 client = Client("http://127.0.0.1:9998") # 检查服务状态 print(client.list_models()) # 初始应为空列表 []
如果连接成功，list_models() 会返回一个空列表，表示当前还没有加载任何模型。
现在进入最激动人心的部分。我们将分别加载一个文本大模型（以 Qwen2.5-7B-Instruct 为例）、一个纯英文模型（以 Llama-3.2-3B-Instruct 为例）和一个语音识别模型（openai/whisper-large-v3）。
首先，我们来加载一个在中文场景下表现非常出色的模型——Qwen2.5-7B-Instruct。
# 第一步：从模型仓库拉取并加载模型 # model_uid 是你给这个模型实例起的名字，方便后续调用 # model_name 指定要加载的具体模型 # model_format 指定模型格式，'ggmlv3' 是量化格式，对 CPU/内存更友好 # quantization 指定量化等级，'q4_0' 在精度和速度间取得较好平衡 model_uid_qwen = client.launch_model( model_name="qwen2.5-7b-instruct", model_format="ggmlv3", quantization="q4_0", # 如果你的机器有 GPU，可以指定设备，加速推理 # n_gpu=1 ) print(f"Qwen2.5 模型加载成功，UID: {model_uid_qwen}")
加载过程需要下载模型文件（约 4-5GB），首次运行时间取决于你的网速。加载成功后，会打印出模型的唯一标识 UID。
第二步：与 Qwen 进行实时对话
模型加载后，我们就可以像调用 OpenAI API 一样与它对话了。
# 获取模型对象 model_qwen = client.get_model(model_uid_qwen) # 进行简单的文本生成 prompt = "请用 Python 写一个快速排序算法的函数，并添加中文注释。" response = model_qwen.chat(prompt=prompt) print("Qwen2.5 回答：") print(response["choices"][0]["message"]["content"]) print("\n" + "="*50 + "\n") # 进行多轮对话（带有历史消息） messages = [ {"role": "system", "content": "你是一个乐于助人的编程助手。"}, {"role": "user", "content": "什么是装饰器（Decorator）？"} ] response_with_history = model_qwen.chat(messages=messages) print("Qwen2.5 回答（带系统指令）：") print(response_with_history["choices"][0]["message"]["content"]) # 继续对话，模型会自动记住上下文 follow_up = {"role": "user", "content": "能给我一个简单的例子吗？"} messages.append(response_with_history["choices"][0]["message"]) messages.append(follow_up) response_followup = model_qwen.chat(messages=messages) print("\nQwen2.5 回答（跟进问题）：") print(response_followup["choices"][0]["message"]["content"])
你会看到模型生成了带有中文注释的代码，并进行了连贯的多轮对话。这就是 '一行代码切换模型' 的魅力——API 和 GPT 完全兼容。
接下来，我们换一个模型，比如 Meta 发布的轻量级但能力不俗的 Llama-3.2-3B-Instruct。操作流程几乎一模一样。
# 加载 Llama-3.2-3B-Instruct 模型 model_uid_llama = client.launch_model( model_name="llama-3.2-3b-instruct", model_format="ggmlv3", quantization="q4_0", ) print(f"Llama-3.2 模型加载成功，UID: {model_uid_llama}") # 获取模型对象 model_llama = client.get_model(model_uid_llama) # 与 Llama3 对话 (这是一个英文为主的模型，我们用英文提问效果更好) prompt_en = "Explain the concept of quantum computing to a high school student in three sentences." response_llama = model_llama.chat(prompt=prompt_en) print("Llama-3.2 回答：") print(response_llama["choices"][0]["message"]["content"])
注意，我们只是改变了 model_name 参数，就从 Qwen 切换到了 Llama3。整个调用代码无需任何改动。
Xinference 同样支持多模态模型。让我们加载 OpenAI 开源的 Whisper-large-v3 模型来进行语音转文字。
重要前提：你需要准备一个音频文件（如.wav, .mp3）。这里我们假设你有一个名为 test_audio.wav 的文件。
# 加载 Whisper-large-v3 语音识别模型 model_uid_whisper = client.launch_model( model_name="whisper-large-v3", model_type="audio" # 语音模型通常不需要指定 format 和 quantization ) print(f"Whisper-large-v3 模型加载成功，UID: {model_uid_whisper}") # 获取模型对象 model_whisper = client.get_model(model_uid_whisper) # 进行语音识别 # 注意：这里需要将音频文件读取为字节流或 base64 编码。 # 以下示例展示从本地文件读取 import base64 audio_path = "test_audio.wav" with open(audio_path, "rb") as f: audio_bytes = f.read() audio_b64 = base64.b64encode(audio_bytes).decode('utf-8') # 调用转录接口 transcription = model_whisper.audio.transcriptions.create( file=audio_b64, model="whisper-large-v3", response_format="verbose_json" # 获取详细输出 ) print("Whisper 识别结果：") print(f"语言：{transcription.language}") print(f"文本：{transcription.text}")
这样，你就拥有了一个本地的、功能强大的语音识别服务。
当你同时运行多个模型时，良好的管理是必要的。
# 1. 查看当前所有已加载的模型 all_models = client.list_models() print("当前运行中的模型：") for model in all_models: print(f"- UID: {model['model_uid']}, Name: {model['model_name']}, Status: {model['status']}") # 2. 终止一个模型（释放内存） # client.terminate_model(model_uid_qwen) # print(f"已终止模型：{model_uid_qwen}") # 3. 复用模型 # 只要模型还在运行，你可以随时在其他地方通过 UID 获取它，无需重新加载。 # 例如，重启 Jupyter 内核后，只需重新连接客户端，然后： # model_qwen = client.get_model('之前记录的 model_uid_qwen') # 即可继续使用。
这是 Xinference 最强大的功能之一。它提供了与 OpenAI 库完全兼容的接口。这意味着，你之前为 GPT 写的代码，几乎可以无缝迁移。
# 使用 openai 库的格式调用（需要安装 openai 包：!pip install openai） from openai import OpenAI # 将 Xinference 服务地址作为 base_url client_openai = OpenAI( base_url="http://127.0.0.1:9998/v1", api_key="not-needed" # Xinference 不需要有效的 API key ) # 使用 ChatCompletion 接口 completion = client_openai.chat.completions.create( model=model_uid_qwen, # 这里填写你要使用的模型 UID messages=[ {"role": "user", "content": "你好，请介绍一下你自己。"} ], stream=True # 支持流式输出 ) # 流式打印结果 print("流式输出：") for chunk in completion: if chunk.choices[0].delta.content is not None: print(chunk.choices[0].delta.content,, flush=True)
看到没？只需改一下 base_url，你的代码就从调用昂贵的 GPT API 变成了调用本地免费的强大开源模型。
通过上面的步骤，我们成功地在 Jupyter Notebook 环境中，利用 Xinference-v1.17.1 搭建了一个本地的、多模型的 AI 推理平台。我们来回顾一下核心收获：
pip install 和 launch_model 两条命令，解决了开源模型部署的所有复杂问题。chat() 或 OpenAI 兼容 API 进行调用，极大降低了开发和切换成本。下一步，你可以尝试：
launch_model 时尝试不同的量化等级（如 q8_0, q5_k_m），在精度和速度之间找到最佳平衡点。http://127.0.0.1:9997），通过图形界面管理模型和进行简单对话。Xinference 就像给你的电脑插上了无数个开源模型的'翅膀'，让你可以自由地在本地探索 AI 的前沿。希望这篇教程能帮你打开这扇门，享受低成本、高性能的 AI 推理乐趣。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online