Xinference 全面介绍和使用指南

适用对象：初学者、有一定 AI/大模型培训和开发基础的技术人员

一、介绍

Xinference 是由 Xorbits 团队开发的一套 本地大模型推理和服务框架，目标是让你像用数据库一样简单地使用 LLM (大语言模型) 和 Embedding 模型，支持 Chat / Completion / Embedding / TTS / STT 等多种任务。

官网：xinference.io
GitHub：github.com/xorbitsai/i...

🤖 模型任务类型说明

类型	全称	含义与应用
Chat	Chat Model	聊天模型，支持多轮对话记忆，如 ChatGLM、Qwen、LLaMA 等
Completion	Text Completion	续写模型，适合代码补全、文本生成，如 GPT-J、RWKV
Embedding	Text Embedding	文本向量化，用于相似度检索、知识库构建，如 BGE、E5 等
TTS	Text to Speech	文本转语音，将文字转为语音播放，如 Bark、Coqui
STT	Speech to Text	语音转文字，用于语音识别，如 Whisper

二、核心特性

1. 支持多模型和多任务

Chat ：Qwen, ChatGLM, LLaMA, Baichuan, Mistral
Embedding ：BGE, Nomic, E5, Instructor
Completion ：GPT-J, Pythia, RWKV
TTS/STT ：Whisper, Bark, Coqui

2. 一行命令启动

bash 复制代码

xinference-local

3. 提供 REST API + OpenAI 符合接口

REST 接口可直接调用
兼容 OpenAI SDK

4. Web UI

简洁易用，支持模型添加、操作、清除
支持自由添加 HuggingFace 模型

5. 分布式和 CPU/GPU 选择

支持单机 CPU ，多 GPU ，简易分布式启动

三、安装指南

1. 依赖

Python >= 3.9
pip / conda 环境

2. pip 安装

bash 复制代码

pip install "xinference[all]"

如果只需基础 REST 接口：

bash 复制代码

pip install xinference

四、启动 Xinference

bash 复制代码

xinference-local --log-level=info

启动后访问：

arduino 复制代码

http://127.0.0.1:9997

如看到 Web UI 界面，表明启动成功。

五、注册模型

1. 注册 Chat 模型

bash 复制代码

curl -X POST http://127.0.0.1:9997/v1/models \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "qwen:0.5b",
    "model_format": "xinference",
    "quantization": "q4",
    "task": "chat"
  }'

2. 注册 Embedding 模型（本地免费推荐）

bash 复制代码

pip install -U sentence-transformers

bash 复制代码

curl -X POST http://127.0.0.1:9997/v1/models \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "bge-base-zh",
    "model_format": "xinference",
    "model_type": "embedding",
    "model_engine": "sentence_transformers"
    }'

或使用 HuggingFace 模型（如 bge-base-zh）：

bash 复制代码

curl -X POST http://127.0.0.1:9997/v1/models \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "bge-base-zh",
    "model_format": "huggingface",
    "model_path": "BAAI/bge-base-zh",
    "task": "embedding",
    "engine": "huggingface"
  }'

六、调用接口

1. Chat

bash 复制代码

curl -X POST http://127.0.0.1:9997/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_uid>",
    "messages": [
      {"role": "user", "content": "你好，请自我介绍"}
    ]
  }'

2. Embedding

bash 复制代码

curl -X POST http://127.0.0.1:9997/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model_uid>",
    "input": ["你好，欢迎使用 Xinference"]
  }'

七、Python SDK 使用

python 复制代码

from xinference.client import Client

client = Client("http://127.0.0.1:9997")
print(client.list_models())

model = client.get_model("qwen-0.5b-chat-xxxx")
response = model.chat("你好啊")
print(response)

八、常见问题和解决

问题：启动时 cluster not available / 连接被拒

关闭 Windows 防火墙、允许 9997 端口
以管理员身份运行端口
更新 ray： pip install -U "ray[default]"

问题：无法接口调用

确保 model_uid 正确
注册模型成功
确保 URL 本地访问

问题：模型注册失败

bge-base-zh 使用 huggingface 模型格式和 engine
sentence_transformers 引擎不支持所有模型

九、推荐配置

场景	配置	说明
初学者	CPU + bge-small-zh	内存占用小，无 GPU 也能用
资料编目	GPU + bge-large-zh	适合 FAISS 指向的文档矩阵化
Chatbot	GPU + ChatGLM3 / Qwen	中文效果优秀，支持多评论区

十、总结

Xinference 是一套高级、用户友好的本地大模型服务框架，适合开发者、培训者、科研人员作为本地方案培训、上线模型调用的重要组件。

它拥有体验好、全能、容易集成的特点，很适合部署到无线环境、文档搜索、自己实验等场景中。

附录：使用 Langchain-Chatchat 搭配免费嵌入模型

方式 1：本地模型（推荐）

dotenv 复制代码

EMBEDDING_MODEL=bge-small-zh
EMBEDDING_MODEL_API_BASE=http://127.0.0.1:9997/v1

前提是在 Xinference 中注册了 bge-small-zh 模型。

方式 2：HuggingFace API（带 token）

dotenv 复制代码

EMBEDDING_MODEL=BAAI/bge-small-zh
EMBEDDING_MODEL_API_BASE=https://api-inference.huggingface.co/pipeline/feature-extraction
EMBEDDING_MODEL_API_KEY=hf_xxx

方式 3：OpenRouter / DeepSeek 免费接口

dotenv 复制代码

EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_MODEL_API_BASE=https://openrouter.ai/api/v1
EMBEDDING_MODEL_API_KEY=sk-xxx

推荐使用本地免费模型，如 bge-small-zh，结合 FAISS 构建知识库，完全免费、离线可用、中文效果好。