Appearance

Xorbits Inference

配置 Xorbits Inference

Xorbits Inference (Xinference) 是一个强大的开源模型推理框架，支持 LLM、Embedding、Rerank 和多模态模型。提供分布式推理、一键部署、OpenAI 兼容 API 等功能。

1. 安装和部署 Xinference ​

1.1 访问 Xinference 官网 ​

访问 Xinference 官网并查看文档：https://inference.readthedocs.io/

GitHub 仓库：https://github.com/xorbitsai/inference

1.2 环境要求 ​

  • 操作系统：Linux、macOS、Windows
  • Python：3.8-3.11
  • GPU：可选（NVIDIA GPU 支持 CUDA）
  • 内存：根据模型大小，建议 16GB+

1.3 安装 Xinference ​

使用 pip 安装 ​

bash
# 安装Xinference
pip install "xinference[all]"

# 验证安装
xinference --version

预期结果：

xinference, version 0.x.x

常见错误：

  • 如果提示 command not found: xinference，说明安装未成功或未加入 PATH
  • 如果提示 Python 版本不兼容，请确保使用 Python 3.8-3.11

使用 Docker 安装 ​

bash
# 拉取Xinference官方镜像
docker pull xprobe/xinference:latest

# 运行Xinference服务
docker run -p 9997:9997 -v $HOME/.xinference:/root/.xinference xprobe/xinference:latest

预期结果：

  • 镜像拉取成功，显示 Status: Downloaded newer image for xprobe/xinference:latest
  • 容器启动后显示日志输出，包含 Starting Xinference at http://0.0.0.0:9997

常见错误：

  • 如果拉取失败，可能是网络问题，尝试配置 Docker 镜像加速
  • 如果端口 9997 被占用，修改 -p 参数使用其他端口

1.4 启动 Xinference 服务 ​

启动本地服务 ​

bash
# 启动Xinference
xinference-local --host 0.0.0.0 --port 9997

预期结果：

Starting Xinference at http://0.0.0.0:9997
Xinference service started successfully
You can now access the web UI at http://localhost:9997

常见错误：

  • 如果提示 Address already in use，说明端口被占用，使用 --port 指定其他端口
  • 如果提示权限错误，尝试使用 sudo 或检查文件权限

启动集群模式 ​

bash
# 启动supervisor（主节点）
xinference-supervisor --host 0.0.0.0 --port 9997

# 启动worker（工作节点）
xinference-worker --endpoint http://supervisor_host:9997

预期结果：

  • Supervisor 启动成功，显示监听地址和端口
  • Worker 连接成功，显示 Connected to supervisor at http://supervisor_host:9997

1.5 部署模型 ​

通过 Web UI 或命令行部署模型：

使用 Web UI ​

  1. 访问：http://localhost:9997
  2. 点击 Launch Model 按钮
  3. 选择模型（如 qwen2.5-7b-instruct）
  4. 配置参数并启动

预期结果：

  • Web UI 显示可用模型列表
  • 点击 Launch 后，模型开始下载（如果本地没有）
  • 模型加载成功后，显示状态为 "Running"
  • 可以看到模型的访问地址，如 http://localhost:9997/v1

常见问题：

  • 如果模型列表为空，检查网络连接或手动下载模型
  • 首次部署会下载模型文件，可能需要较长时间（取决于模型大小）
  • 如果内存不足，选择参数量更小的模型

使用命令行 ​

bash
# 部署Qwen 2.5 7B模型
xinference launch --model-name qwen2.5-7b-instruct --size-in-billions 7

# 查看已部署的模型
xinference list

预期结果：

Model launched successfully
Model UID: qwen2.5-7b-instruct-xxxxx
Model is now available at: http://localhost:9997/v1/models/qwen2.5-7b-instruct-xxxxx

查看已部署模型的输出示例：

UID                                   Name                      Type    Status
qwen2.5-7b-instruct-xxxxx            qwen2.5-7b-instruct       LLM     Running

常见错误：

  • 如果提示模型不存在，使用 xinference registrations 查看可用模型
  • 如果启动失败，检查日志了解具体错误原因

1.6 验证服务运行 ​

bash
# 检查服务状态
curl http://localhost:9997/v1/models

正确返回结果示例：

json
{
  "object": "list",
  "data": [
    {
      "id": "qwen2.5-7b-instruct-xxxxx",
      "object": "model",
      "created": 1699234567,
      "owned_by": "xinference",
      "permission": []
    }
  ]
}

如果返回上述 JSON 内容，说明 Xinference 服务启动成功并且模型已部署。

错误情况：

  1. 连接失败：

    bash
    curl: (7) Failed to connect to localhost port 9997: Connection refused

    说明服务未启动或端口配置错误，请检查服务是否正常运行。

  2. 返回空列表：

    json
    {
  "object": "list",
  "data": []
}

    说明服务正常运行，但还没有部署任何模型，需要先部署模型。

  3. 404 错误：

    json
    {"detail": "Not Found"}

    说明访问路径错误，确认使用正确的 API 端点 /v1/models。

2. 在 CueMate 中配置 Xinference 模型 ​

2.1 进入模型设置页面 ​

登录 CueMate 系统后，点击右上角下拉菜单的 模型设置。

进入模型设置

2.2 添加新模型 ​

点击右上角的 添加模型 按钮。

点击添加模型

2.3 选择 Xorbits Inference 服务商 ​

在弹出的对话框中：

  1. 服务商类型：选择 Xorbits Inference
  2. 点击后 自动进入下一步

选择 Xinference

2.4 填写配置信息 ​

在配置页面填写以下信息：

基础配置 ​

  1. 模型名称：为这个模型配置起个名字（例如：Xinference Qwen 2.5）
  2. API URL：保持默认 http://localhost:9997/v1（或修改为 Xinference 服务地址）
  3. API Key：可选，Xinference 服务启动时配置了 --api-key 参数时填写
  4. 模型版本：输入已部署的模型名称

2025 推荐模型：

  • Qwen 2.5 系列：
    • qwen2.5-72b-instruct：Qwen 2.5 72B 对话模型
    • qwen2.5-32b-instruct：Qwen 2.5 32B 对话模型
    • qwen2.5-14b-instruct：Qwen 2.5 14B 对话模型（推荐）
    • qwen2.5-7b-instruct：Qwen 2.5 7B 对话模型
  • Qwen 2.5 Coder 系列：
    • qwen2.5-coder-32b-instruct：代码生成 32B
    • qwen2.5-coder-7b-instruct：代码生成 7B
  • DeepSeek R1 系列：
    • deepseek-r1-8b：DeepSeek R1 8B 推理增强模型
  • Llama 3 系列：
    • llama-3.3-70b-instruct：Llama 3.3 70B 对话模型
    • llama-3.1-70b-instruct：Llama 3.1 70B 对话模型
    • llama-3.1-8b-instruct：Llama 3.1 8B 对话模型
  • 其他推荐：
    • mistral-7b-instruct-v0.3：Mistral 7B 对话模型
    • gemma-2-27b-it：Gemma 2 27B 对话模型
    • gemma-2-9b-it：Gemma 2 9B 对话模型
    • glm-4-9b-chat：GLM-4 9B 对话模型

注意：模型版本必须是已在 Xinference 中部署的模型。

填写基础配置

高级配置（可选） ​

展开 高级配置 面板，可以调整以下参数：

CueMate 界面可调参数：

  1. 温度（temperature）：控制输出随机性

    • 范围：0-2（大部分模型），0-1（Qwen 系列）
    • 推荐值：0.7
    • 作用：值越高输出越随机创新，值越低输出越稳定保守
    • 使用建议：
      • 创意写作/头脑风暴：1.0-1.5
      • 常规对话/问答：0.7-0.9
      • 代码生成/精确任务：0.3-0.5
    • 注意：Qwen 系列模型的 temperature 最大值为 1，不是 2

  2. 输出最大 tokens（max_tokens）：限制单次输出长度

    • 范围：256 - 131072（根据模型而定）
    • 推荐值：8192
    • 作用：控制模型单次响应的最大字数
    • 模型限制：
      • Qwen2.5 系列：最大 32K tokens
      • Llama 3.1/3.3 系列：最大 131K tokens
      • DeepSeek R1 系列：最大 65K tokens
      • Mistral 系列：最大 32K tokens
      • Gemma 2 系列：最大 8K tokens
    • 使用建议：
      • 简短问答：1024-2048
      • 常规对话：4096-8192
      • 长文生成：16384-32768
      • 超长文档：65536-131072（仅支持的模型）

高级配置

Xinference API 支持的其他高级参数：

虽然 CueMate 界面只提供 temperature 和 max_tokens 调整，但如果你通过 API 直接调用 Xinference，还可以使用以下高级参数（Xinference 采用 OpenAI 兼容的 API 格式）：

  1. top_p（nucleus sampling）

    • 范围：0-1
    • 默认值：1
    • 作用：从概率累积达到 p 的最小候选集中采样
    • 与 temperature 的关系：通常只调整其中一个
    • 使用建议：
      • 保持多样性但避免离谱：0.9-0.95
      • 更保守的输出：0.7-0.8

  2. top_k

    • 范围：0-100
    • 默认值：50
    • 作用：从概率最高的 k 个候选词中采样
    • 使用建议：
      • 更多样化：50-100
      • 更保守：10-30

  3. frequency_penalty（频率惩罚）

    • 范围：-2.0 到 2.0
    • 默认值：0
    • 作用：降低重复相同词汇的概率（基于词频）
    • 使用建议：
      • 减少重复：0.3-0.8
      • 允许重复：0（默认）

  4. presence_penalty（存在惩罚）

    • 范围：-2.0 到 2.0
    • 默认值：0
    • 作用：降低已出现过的词汇再次出现的概率（基于是否出现）
    • 使用建议：
      • 鼓励新话题：0.3-0.8
      • 允许重复话题：0（默认）

  5. stop（停止序列）

    • 类型：字符串或数组
    • 默认值：null
    • 作用：当生成内容包含指定字符串时停止
    • 示例：["###", "用户:", "\n\n"]
    • 使用场景：
      • 结构化输出：使用分隔符控制格式
      • 对话系统：防止模型代替用户说话

  6. stream（流式输出）

    • 类型：布尔值
    • 默认值：false
    • 作用：启用 SSE 流式返回，边生成边返回
    • CueMate 中：自动处理，无需手动设置

  7. repetition_penalty

    • 类型：浮点数
    • 范围：1.0-2.0
    • 默认值：1.0
    • 作用：Xinference 特有参数，对已生成的 token 进行惩罚以减少重复
    • 使用建议：
      • 减少重复内容：1.1-1.3
      • 正常输出：1.0（默认）

参数组合建议：

序号场景temperaturemax_tokenstop_ptop_kfrequency_penaltypresence_penalty
1创意写作1.0-1.24096-81920.95500.50.5
2代码生成0.2-0.52048-40960.9400.00.0
3问答系统0.71024-20480.9500.00.0
4摘要总结0.3-0.5512-10240.9300.00.0
5头脑风暴1.2-1.52048-40960.95600.80.8

2.5 测试连接 ​

填写完配置后，点击 测试连接 按钮，验证配置是否正确。

测试连接

如果配置正确，会显示测试成功的提示，并返回模型的响应示例。

测试成功

如果配置错误，会显示测试错误的日志，并且可以通过日志管理，查看具体报错信息。

2.6 保存配置 ​

测试成功后，点击 保存 按钮，完成模型配置。

保存配置

3. 使用模型 ​

通过右上角下拉菜单，进入系统设置界面，在大模型供应商栏目选择想要使用的模型配置。

配置完成后，可以在面试训练、问题生成等功能中选择使用此模型， 当然也可以在面试的选项中单此选择此次面试的模型配置。

选择模型

4. 支持的模型列表 ​

4.1 Qwen 2.5 系列（推荐） ​

序号模型名称模型 ID参数量最大输出适用场景
1Qwen 2.5 72B Instructqwen2.5-72b-instruct72B32K tokens超大规模任务
2Qwen 2.5 32B Instructqwen2.5-32b-instruct32B32K tokens大规模任务
3Qwen 2.5 14B Instructqwen2.5-14b-instruct14B32K tokens中等规模任务
4Qwen 2.5 7B Instructqwen2.5-7b-instruct7B32K tokens通用场景、性价比高
5Qwen 2.5 Coder 32Bqwen2.5-coder-32b-instruct32B32K tokens代码生成大型
6Qwen 2.5 Coder 7Bqwen2.5-coder-7b-instruct7B32K tokens代码生成中型

4.2 DeepSeek R1 系列 ​

序号模型名称模型 ID参数量最大输出适用场景
1DeepSeek R1 8Bdeepseek-r1-8b8B65K tokens推理增强对话

4.3 Llama 3 系列 ​

序号模型名称模型 ID参数量最大输出适用场景
1Llama 3.3 70B Instructllama-3.3-70b-instruct70B131K tokens超长上下文
2Llama 3.1 70B Instructllama-3.1-70b-instruct70B131K tokens高质量对话
3Llama 3.1 8B Instructllama-3.1-8b-instruct8B131K tokens通用对话

4.4 其他推荐模型 ​

序号模型名称模型 ID参数量最大输出适用场景
1Mistral 7B Instructmistral-7b-instruct-v0.37B32K tokens多语言对话
2Gemma 2 27B ITgemma-2-27b-it27B8K tokensGoogle 旗舰模型
3Gemma 2 9B ITgemma-2-9b-it9B8K tokensGoogle 中型模型
4GLM-4 9B Chatglm-4-9b-chat9B131K tokens智谱 GLM 最新版

Xinference 特色功能 ​

4.5 模型设置 ​

  • 一键部署：支持 100+开源模型
  • 版本管理：同一模型的多个版本
  • 自动下载：首次使用自动下载模型

4.6 分布式推理 ​

bash
# 启动集群supervisor
xinference-supervisor -H 0.0.0.0 -p 9997

# 在其他机器启动worker
xinference-worker -e http://supervisor_ip:9997

4.7 内置 Embedding ​

bash
# 部署embedding模型
xinference launch --model-name bge-large-zh --model-type embedding

5. 常见问题 ​

5.1 模型下载失败 ​

现象：首次部署模型时下载失败

解决方案：

  1. 检查网络连接，确保可以访问 HuggingFace
  2. 设置镜像加速：export HF_ENDPOINT=https://hf-mirror.com
  3. 预先下载模型到 ~/.xinference/cache
  4. 使用本地模型路径

5.2 端口冲突 ​

现象：启动服务时提示端口被占用

解决方案：

  1. 修改启动端口：xinference-local --port 9998
  2. 检查并关闭占用端口的进程
  3. 使用 lsof -i :9997 查看端口占用

5.3 内存不足 ​

现象：部署模型时提示内存不足

解决方案：

  1. 选择参数量更小的模型
  2. 使用量化版本
  3. 配置 GPU 加速
  4. 增加系统内存

5.4 模型列表为空 ​

现象：访问/v1/models 返回空列表

解决方案：

  1. 确认已部署至少一个模型
  2. 使用 xinference list 查看部署状态
  3. 检查 Xinference 服务日志
  4. 重启 Xinference 服务

性能优化 ​

5.5 GPU 加速 ​

bash
# 自动检测并使用GPU
xinference launch --model-name qwen2.5-7b-instruct

# 指定GPU设备
CUDA_VISIBLE_DEVICES=0,1 xinference-local

5.6 量化加速 ​

bash
# 使用4-bit量化
xinference launch --model-name qwen2.5-7b-instruct --quantization 4-bit

5.7 批处理优化 ​

调整 xinference.toml 配置文件：

toml
[inference]
max_batch_size = 32
max_concurrent_requests = 256

优势与特点 ​

5.8 易用性 ​

  • Web UI 管理界面
  • 一键部署模型
  • OpenAI 兼容 API

5.9 功能丰富 ​

  • 支持 LLM、Embedding、Rerank
  • 多模态模型支持
  • 分布式推理集群

5.10 生产就绪 ​

  • 高可用架构
  • 监控和日志
  • 负载均衡

相关链接 ​

Released under the GPL-3.0 License.

Copyright © 2025-present CueMate Team