Xinference 大模型部署与分布式推理框架使用指南

注意：

Xinference 默认使用 `<HOME>/.xinference` 作为主目录存储一些必要信息，如：日志文件和模型文件

通过配置环境变量 `XINFERENCE_HOME` 修改主目录，比如：XINFERENCE_HOME=/tmp/xinference xinference-local --host 0.0.0.0 --port 9997

查看存储信息

(xinference) root@master:~# ls .xinference/
cache  logs
(xinference) root@master:~# ls .xinference/cache/
chatglm3-pytorch-6b
(xinference) root@master:~# ls .xinference/logs/
local_1721628924181  local_1721629451488  local_1721697225558  local_1721698858667

通过访问 http://localhost:9777 地址来使用 Web GUI 界面

通过访问 http://localhost:9997/docs 来查看 API 文档。

模型部署

1. 搜索选择模型

点击 Launch Model 菜单，选择 LANGUAGE MODELS 标签，输入关键词以搜索需要部署的模型。这里以搜索 ChatGLM3 模型为例。

2. 模型参数配置

模型的具体参数配置参考下文：模型参数配置说明

3. 开始部署模型

模型参数填写完成后，点击卡片左下方的火箭图标按钮开始部署模型。后台根据配置参数下载量化或非量化 LLM 模型。

注意：当运行一个模型时，第一次运行是要从默认或指定的模型站点下载模型参数。当下载完成后，Xinference 本地会有缓存的处理，以后再运行相同的模型不需要重新下载。

4. 已部署模型列表

部署完成后，界面自动跳转到 Running Models 菜单，在 LANGUAGE MODELS 标签中，可以看到部署好的模型。

5. LLM 模型对话

点击 Launch Web UI 图标，自动打开 LLM 模型的 Web 界面，可以直接与 LLM 模型进行对话。

模型参数配置说明

在部署 LLM 模型时，有以下参数可供选择：

1. 必选配置：

Model Engine：模型推理引擎，根据模型不同，可能支持的引擎不同

Model Format: 模型格式，可以选择量化 (ggml、gptq 等) 和非量化 (pytorch) 的格式

Model Size：模型的参数量大小，不同模型参数量不同，可能是：6B、7B、13B、70B 等

Quantization：量化精度，有 4bit、8bit 等量化精度选择

N-GPU：模型使用的 GPU 数量：可选择 Auto、CPU、GPU 数量，默认 Auto

Replica：模型的副本，默认为 1

点击 chatglm3 卡片，填写部署模型的相关信息。

2. 可选配置：

Model UID: 模型的 UID，可理解为模型自定义名称，默认用原始模型名称

Request Limits: 模型的请求限制数量，默认为 None。None 表示此模型没有限制

Worker Ip: 指定分布式场景中模型所在的工作器 ip

Gpu Idx: 指定模型所在的 GPU 索引

Download hub: 模型从哪里下载，可选：none、huggingface、modelscope

3. LoRA 配置：

Lora Model Config：PEFT（参数高效微调）模型和路径的列表

Lora Load Kwargs for Image Model：图像模型的 lora 加载参数字典

Lora Fuse Kwargs for Image Model：图像模型的 lora fuse 参数字典

4. 传递给推理引擎的其他参数：

API 接口

概述

除了使用 LLM 模型的 Web 界面进行操作外，Xinference 还提供了 API 接口，通过调用 API 接口来使用 LLM 模型。

在 API 文档中，存在大量 API 接口，不仅有 LLM 模型的接口，还有其他模型 (如 Embedding) 的接口，并且这些接口都是兼容 OpenAI API 的接口。

通过访问 http://localhost:9997/docs 来查看 API 文档。

对话接口

使用 Curl 工具调用对话接口

curl -X 'POST' \
  'http://localhost:9997/v1/chat/completions' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "chatglm3",
    "messages": [
      {
        "role": "user",
        "content": "你好啊"
      }
    ]
  }'

响应示例：

{"id":"chat73f8c754-4898-11ef-89f6-000c2981d002","object":"chat.completion","created":1721700508,"model":"chatglm3","choices":[{"index":0,"message":{"role":"assistant","content":"你好👋！我是人工智能助手 ChatGLM3-6B，很高兴见到你，欢迎问我任何问题。"},"finish_reason":"stop"}],"usage":{"prompt_tokens":-1,"completion_tokens":-1,"total_tokens":-1}}

模型列表

使用 Curl 工具调用获取模型列表

curl -X 'GET' \
  'http://localhost:9997/v1/models' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json'

响应示例：

{"object":"list","data":[{"id":"chatglm3","object":"model","created":0,"owned_by":"xinference","model_type":"LLM","address":"0.0.0.0:38145","accelerators":["0"],"model_name":"chatglm3","model_lang":["en","zh"],"model_ability":["chat","tools"],"model_description":"ChatGLM3 is the third generation of ChatGLM, still open-source and trained on Chinese and English data.","model_format":"pytorch","model_size_in_billions":6,"model_family":"chatglm3","quantization":"4-bit","model_hub":"modelscope","revision":"v1.0.2","context_length":8192,"replica":1}]}

嵌入模型

使用 Curl 工具调用嵌入模型接口

curl -X 'POST' \
  'http://localhost:9997/v1/embeddings' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "嵌入模型名称、UID",
    "input": "你好啊"
  }'

Rerank 模型

使用 Curl 工具调用 Rerank 模型接口

curl -X 'POST' \
  'http://localhost:9997/v1/rerank' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
	  "model": "bge-reranker-base",
	  "query": "你是谁？",
	  "documents": [
		"你是一名乐于助人的 AI 助手。",
		"你的名字叫'rerank'"
	  ]
	}'

使用 Xinference SDK

安装 Xinference 的 Python SDK，使用以下命令安装最少依赖。注意：版本必须和 Xinference 服务的版本保持匹配。

pip install xinference-client==${SERVER_VERSION}

from xinference.client import RESTfulClient

client = RESTfulClient("http://127.0.0.1:9997")
# 注意：my-llm 是参数 `--model-uid` 指定的值
model = client.get_model("my-llm")
print(model.chat(
    prompt="你好啊",
    system_prompt="你是一个乐于助人的 AI 助手。",
    chat_history=[]
))

使用 OpenAI SDK

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

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

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

命令行工具

概述

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

执行以下命令以安装 xinference 命令行工具

pip install xinference

查看帮助命令

(xinference) root@master:~# xinference --help
Usage: xinference [OPTIONS] COMMAND [ARGS]...

  Xinference command-line interface for serving and deploying models.

Options:
  -v, --version       Show the current version of the Xinference tool.
  --log-level TEXT    Set the logger level. Options listed from most log to
                      least log are: DEBUG > INFO > WARNING > ERROR > CRITICAL
                      (Default level is INFO)
  -H, --host TEXT     Specify the host address for the Xinference server.
  -p, --port INTEGER  Specify the port number for the Xinference server.
  --help              Show this message to exit.

Commands:
  cached         List all cached models in Xinference.
  cal-model-mem  calculate gpu mem usage with specified model size and...
  chat           Chat with a running LLM.
  engine         Query the applicable inference engine by model name.
  generate       Generate text using a running LLM.
  launch         Launch a model with the Xinference framework with the...
  list           List all running models in Xinference.
  login          Login when the cluster is authenticated.
  register       Register a new model with Xinference for deployment.
  registrations  List all registered models in Xinference.
  remove-cache   Remove selected cached models in Xinference.
  stop-cluster   Stop a cluster using the Xinference framework with the...
  terminate      Terminate a deployed model through unique identifier...
  unregister     Unregister a model from Xinference, removing it from...
  vllm-models    Query and display models compatible with vLLM.

启动模型

使用 Xinference 框架启动一个模型，Xinference 提供了 xinference launch 命令帮助查询相关的参数配置。

(xinference) root@master:~# xinference launch --help
Usage: xinference launch [OPTIONS]

  Launch a model with the Xinference framework with the given parameters.

Options:
  -e, --endpoint TEXT             Xinference endpoint.
  -n, --model-name TEXT           Provide the name of the model to be
                                  launched.  [required]
  -t, --model-type TEXT           Specify type of model, LLM as default.
  -en, --model-engine TEXT        Specify the inference engine of the model
                                  when launching LLM.
  -u, --model-uid TEXT            Specify UID of model, default is None.
  -s, --size-in-billions TEXT     Specify the model size in billions of
                                  parameters.
  -f, --model-format TEXT         Specify the format of the model, e.g. pytorch, ggmlv3, etc.
  -q, --quantization TEXT         Define the quantization settings for the
                                  model.
  -r, --replica INTEGER           The replica count of the model, default is
                                  1.
  --n-gpu TEXT                    The number of GPUs used by the model,
                                  default is "auto".
  -lm, --lora-modules <TEXT TEXT>...
                                  LoRA module configurations in the format
                                  name=path. Multiple modules can be
                                  specified.
  -ld, --image-lora-load-kwargs <TEXT TEXT>...
  -fd, --image-lora-fuse-kwargs <TEXT TEXT>...
  --worker-ip TEXT                Specify which worker this model runs on by
                                  ip, for distributed situation.
  --gpu-idx TEXT                  Specify which GPUs of a worker this model
                                  can run on, separated with commas.
  --trust-remote-code BOOLEAN     Whether or not to allow for custom models
                                  defined on the Hub in their own modeling
                                  files.
  -ak, --api-key TEXT             Api-Key for access xinference api with
                                  authorization.
  --help                          Show this message to exit.

启动一个模型：

xinference launch --model-engine transformers --model-uid my-llm --model-name chatglm3 --quantization 4-bit --size-in-billions 6 --model-format pytorch

参数说明：

--model-engine transformers：指定模型的推理引擎
--model-uid：指定模型的 UID，如果没有指定，则随机生成一个 ID
--model-name：指定模型名称
--quantization: 指定模型量化精度
--size-in-billions：指定模型参数大小，以十亿为单位
--model-format：指定模型的格式

成功启动日志如下：

(xinference) root@master:~# xinference launch --model-engine transformers --model-uid myllm --model-name chatglm3 --quantization 4-bit --size-in-billions 6 --model-format pytorch
Launch model name: chatglm3 with kwargs: {}
Model uid: myllm

访问 http://localhost:9777，查看已运行的模型。

引擎参数

当加载 LLM 模型时，推理引擎与模型的参数息息相关。Xinference 提供了 xinference engine 命令帮助查询相关的参数组合。

(xinference) root@master:~# xinference engine --help
Usage: xinference engine [OPTIONS]

  Query the applicable inference engine by model name.

Options:
  -n, --model-name TEXT           The model name you want to query.
                                  [required]
  -en, --model-engine TEXT        Specify the `model_engine` to query the
                                  corresponding combination of other
                                  parameters.
  -f, --model-format TEXT         Specify the `model_format` to query the
                                  corresponding combination of other
                                  parameters.
  -s, --model-size-in-billions TEXT
                                  Specify the `model_size_in_billions` to
                                  query the corresponding combination of other
                                  parameters.
  -q, --quantization TEXT         Specify the `quantization` to query the
                                  corresponding combination of other
                                  parameters.
  -e, --endpoint TEXT             Xinference endpoint.
  -ak, --api-key TEXT             Api-Key for access xinference api with
                                  authorization.
  --help                          Show this message to exit.

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

(xinference) root@master:~# xinference engine --model-name chatglm3
Name      Engine        Format      Size (in billions)  Quantization
--------  ------------  --------  --------------------  --------------
chatglm3  Transformers  pytorch                      6  4-bit
chatglm3  Transformers  pytorch                      6  8-bit
chatglm3  Transformers  pytorch                      6  none
chatglm3  vLLM          pytorch                      6  none

2. 想将 chatglm3 跑在 vllm、transformers 推理引擎上，但是不知道什么样的其他参数符合这个要求

(xinference) root@master:~# xinference engine --model-name chatglm3 --model-engine vllm
Name      Engine    Format      Size (in billions)  Quantization
--------  --------  --------  --------------------  --------------
chatglm3  vLLM      pytorch                      6  none

(xinference) root@master:~#  xinference engine --model-name chatglm3 --model-engine transformers
Name      Engine        Format      Size (in billions)  Quantization
--------  ------------  --------  --------------------  --------------
chatglm3  Transformers  pytorch                      6  4-bit
chatglm3  Transformers  pytorch                      6  8-bit
chatglm3  Transformers  pytorch                      6  none

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

chatglm3 模型不支持参数： --model-format ggufv2

(xinference) root@master:~# xinference engine --model-name qwen-chat -f ggufv2
Name       Engine     Format      Size (in billions)  Quantization
---------  ---------  --------  --------------------  --------------
qwen-chat  llama.cpp  ggufv2                       7  Q4_K_M
qwen-chat  llama.cpp  ggufv2                      14  Q4_K_M

其他操作

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

xinference registrations -t LLM

列出所有在运行的模型：

xinference list

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

xinference terminate --model-uid "my-llm"

集成 LoRA

Xinference 可以在启动 LLM 和 image 模型时连带一个 LoRA 微调模型用以辅助基础模型。

启动时集成 LoRA

Xinference 目前不会涉及管理 LoRA 模型。用户需要首先下载对应的 LoRA 模型，然后将模型存储路径提供给 Xinference。

xinference launch <options>
--lora-modules <lora_name1> <lora_model_path1>
--lora-modules <lora_name2> <lora_model_path2>
--image-lora-load-kwargs <load_params1> <load_value1>
--image-lora-load-kwargs <load_params2> <load_value2>
--image-lora-fuse-kwargs <fuse_params1> <fuse_value1>
--image-lora-fuse-kwargs <fuse_params2> <fuse_value2>

from xinference.client import Client

client = Client("http://<XINFERENCE_HOST>:<XINFERENCE_PORT>")

lora_model1={'lora_name': <lora_name1>, 'local_path': <lora_model_path1>}
lora_model2={'lora_name': <lora_name2>, 'local_path': <lora_model_path2>}
lora_models=[lora_model1, lora_model2]
image_lora_load_kwargs={'<load_params1>': <load_value1>, '<load_params2>': <load_value2>},
image_lora_fuse_kwargs={'<fuse_params1>': <fuse_value1>, '<fuse_params2>': <fuse_value2>}

peft_model_config = {
"image_lora_load_kwargs": image_lora_load_params,
"image_lora_fuse_kwargs": image_lora_fuse_params,
"lora_list": lora_models
}

client.launch_model(
    <other_options>,
    peft_model_config=peft_model_config
)

注意：image_lora_load_kwargs 和 image_lora_fuse_kwargs 选项只应用于 image 模型。它们对应于 diffusers 库的 load_lora_weights 和 fuse_lora 接口中的额外参数。如果启动的是 LLM 模型，则无需设置这些选项。

应用时集成 LoRA

对于大语言模型，使用时指定其中一个 lora。具体地，在 generate_config 参数中配置 lora_name 参数。lora_name 对应 launch 过程中你的配置。

from xinference.client import Client

client = Client("http://<XINFERENCE_HOST>:<XINFERENCE_PORT>")
model = client.get_model("<model_uid>")
model.chat(
    "<prompt>",
    <other_options>,
    generate_config={"lora_name": "<your_lora_name>"}
)