适用对象:初学者、有一定 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 模型(本地免费推荐)
注册 Embedding 模型前要安装 sentence_transformers 引擎,否则会启动失败。
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 构建知识库,完全免费、离线可用、中文效果好。