使用

本地运行 Xinference

让我们以一个经典的大语言模型 llama-2-chat 来展示如何在本地用 Xinference 运行大模型。

在这个快速入门之后，可以继续学习如何在一个分布式集群环境下部署 Xinference。

拉起本地服务

首先，请根据这个 文档 的指导确保本地安装了 Xinference。使用以下命令拉起本地的 Xinference 服务：

shelloutput

xinference-local --host 0.0.0.0 --port 9997

备注

默认情况下，Xinference 会使用 <HOME>/.xinference 作为主目录来存储一些必要的信息，比如日志文件和模型文件，其中 <HOME> 就是当前用户的主目录。

你可以通过配置环境变量 XINFERENCE_HOME 修改主目录， 比如：

XINFERENCE_HOME=/tmp/xinference xinference-local --host 0.0.0.0 --port 9997

恭喜！你已经在本地拉起了 Xinference 服务。一旦 Xinference 服务运行起来，可以有多种方式来使用，包括使用网页、cURL 命令、命令行或者是 Xinference 的 Python SDK。

可以通过访问 http://127.0.0.1:9997/ui 来使用 UI，访问 http://127.0.0.1:9997/docs 来查看 API 文档。

可以通过以下命令安装后，利用 Xinference 命令行工具或者 Python 代码来使用：

pip install xinference

命令行工具是 xinference。可以通过以下命令查看有哪些可以使用的命令：

shelloutput

xinference --help

如果只需要安装 Xinference 的 Python SDK，可以使用以下命令安装最少依赖。需要注意的是版本必须和 Xinference 服务的版本保持匹配。

pip install xinference-client==${SERVER_VERSION}

关于模型的推理引擎

自 v0.11.0 版本开始，在加载 LLM 模型之前，你需要指定具体的推理引擎。当前，Xinference 支持以下推理引擎：

• vllm

• sglang

• llama.cpp

• transformers

关于这些推理引擎的详细信息，请参考 这里 。

注意，当加载 LLM 模型时，所能运行的引擎与 model_format 和 quantization 参数息息相关。

Xinference 提供了 xinference engine 命令帮助你查询相关的参数组合。

例如：

1. 我想查询与 qwen-chat 模型相关的参数组合，以决定它能够怎样跑在各种推理引擎上。

xinference engine -e <xinference_endpoint> --model-name qwen-chat

1. 我想将 qwen-chat 跑在 VLLM 推理引擎上，但是我不知道什么样的其他参数符合这个要求。

xinference engine -e <xinference_endpoint> --model-name qwen-chat --model-engine vllm

1. 我想加载 GGUF 格式的 qwen-chat 模型，我需要知道其余的参数组合。

xinference engine -e <xinference_endpoint> --model-name qwen-chat -f ggufv2

总之，相比于之前的版本，当加载 LLM 模型时，需要额外传入 model_engine 参数。你可以通过 xinference engine 命令查询你想运行的推理引擎与其他参数组合的关系。

运行 Llama-2

让我们来运行一个内置的 llama-2-chat 模型。当你需要运行一个模型时，第一次运行是要从HuggingFace 下载模型参数，一般来说需要根据模型大小下载10到30分钟不等。当下载完成后，Xinference本地会有缓存的处理，以后再运行相同的模型不需要重新下载。

备注

Xinference 也允许从其他模型托管平台下载模型。可以通过在拉起 Xinference 时指定环境变量，比如，如果想要从 ModelScope 中下载模型，可以使用如下命令：

XINFERENCE_MODEL_SRC=modelscope xinference-local --host 0.0.0.0 --port 9997

可以使用 --model-uid 或者 -u 参数指定模型的 UID，如果没有指定，Xinference 会随机生成一个 ID，下面的命令就是手动指定了 ID 为 my-llama-2:

shellcURLPythonoutput

xinference launch --model-engine <inference_engine> -u my-llama-2 -n llama-2-chat -s 13 -f pytorch

备注

对于一些推理引擎，比如 vllm，用户需要在运行模型时指定引擎相关的参数，这种情况下直接在命令行中指定对应的参数名和值即可，比如：

xinference launch --model-engine vllm -u my-llama-2 -n llama-2-chat -s 13 -f pytorch --gpu_memory_utilization 0.9

在运行模型时，gpu_memory_utilization=0.9 会传到 vllm 后端。

到这一步，恭喜你已经成功通过 Xinference 将 llama-2-chat 运行起来了。一旦这个模型在运行中，我们可以通过命令行、cURL 或者是 Python 代码来预支交互：

cURLPythonoutput

curl -X 'POST' \
  'http://127.0.0.1:9997/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "my-llama-2",
    "messages": [
        {
            "role": "system",
            "content": "You are a helpful assistant."
        },
        {
            "role": "user",
            "content": "What is the largest animal?"
        }
    ]
  }'

Xinference 提供了与 OpenAI 兼容的 API，所以可以将 Xinference 运行的模型当成 OpenAI的本地替代。比如：

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:9997/v1", api_key="not used actually")

response = client.chat.completions.create(
    model="my-llama-2",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the largest animal?"}
    ]
)
print(response)

以下是支持的 OpenAI 的 API：

• 对话生成：https://platform.openai.com/docs/api-reference/chat

• 生成: https://platform.openai.com/docs/api-reference/completions

• 向量生成：https://platform.openai.com/docs/api-reference/embeddings

管理模型

除了启动模型，Xinference 提供了管理模型整个生命周期的能力。同样的，你可以使用命令行、cURL 以及 Python 代码来管理：

可以列出所有 Xinference 支持的指定类型的模型：

shellcURLPython

xinference registrations -t LLM

接下来的命令可以列出所有在运行的模型：

shellcURLPython

xinference list

当你不需要某个正在运行的模型，可以通过以下的方式来停止它并释放资源：

shellcURLPython

xinference terminate --model-uid "my-llama-2"

集群中部署 Xinference

若要在集群环境中部署 Xinference，需要在一台机器中启动 supervisor 节点，并在当前或者其他节点启动 worker 节点

首先，根据 文档 确保所有的服务器上都安装了 Xinference。接下来按照步骤：

启动 Supervisor

在服务器上执行以下命令来启动 Supervisor 节点：

xinference-supervisor -H "${supervisor_host}"

用当前节点的 IP 来替换 ${supervisor_host}。

可以在 http://${supervisor_host}:9997/ui 访问 web UI，在 http://${supervisor_host}:9997/docs 访问 API 文档。

启动 Worker

在需要启动 Xinference worker 的机器上执行以下命令：

xinference-worker -e "http://${supervisor_host}:9997" -H "${worker_host}"

备注

需要注意的是，必须使用当前Worker节点的 IP 来替换 ${worker_host}。

备注

需要注意的是，如果你需要通过命令行与集群交互，应该通过 -e 或者 --endpoint 参数来指定 supervisor 的地址，比如：

xinference launch -n llama-2-chat -s 13 -f pytorch -e "http://${supervisor_host}:9997"

使用 Docker 部署 Xinference

用以下命令在容器中运行 Xinference：

在拥有英伟达显卡的机器上运行

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 --gpus all xprobe/xinference:<your_version> xinference-local -H 0.0.0.0 --log-level debug

在只有 CPU 的机器上运行

docker run -e XINFERENCE_MODEL_SRC=modelscope -p 9998:9997 xprobe/xinference:<your_version>-cpu xinference-local -H 0.0.0.0 --log-level debug

将 <your_version> 替换为 Xinference 的版本，比如 v0.10.3，可以用 latest 来用于最新版本。

更多 docker 使用，请参考 使用 docker 镜像。

更多

恭喜你，已经初步掌握了 Xinference 的用法！为了帮助你更好地使用工具，下面是其他的一些文档和指导资源：

• 如何使用 Python 创建不同类型的模型

• 选择正确的推理引擎