适用对象：初学者、有一定 AI/大模型培训和开发基础的技术人员
一、介绍
Xinference 是由 Xorbits 团队开发的一套 本地大模型推理和服务框架，目标是让你像用数据库一样简单地使用 LLM (大语言模型) 和 Embedding 模型，支持 Chat / Completion / Embedding / TTS / STT 等多种任务。
- 官网：xinference.ioGitHub：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, MistralEmbedding ：BGE, Nomic, E5, InstructorCompletion ：GPT-J, Pythia, RWKVTTS/STT ：Whisper, Bark, Coqui
2. 一行命令启动
xinference-local3. 提供 REST API + OpenAI 符合接口
- REST 接口可直接调用兼容 OpenAI SDK
4. Web UI
- 简洁易用，支持模型添加、操作、清除支持自由添加 HuggingFace 模型
5. 分布式和 CPU/GPU 选择
- 支持单机 CPU ，多 GPU ，简易分布式启动
三、安装指南
1. 依赖
- Python >= 3.9pip / conda 环境
2. pip 安装
pip install "xinference[all]"如果只需基础 REST 接口：
pip install xinference四、启动 Xinference
xinference-local --log-level=info启动后访问：
http://127.0.0.1:9997如看到 Web UI 界面，表明启动成功。
五、注册模型
1. 注册 Chat 模型
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 引擎，否则会启动失败。
pip install -U sentence-transformerscurl -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）：
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
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
curl -X POST http://127.0.0.1:9997/v1/embeddings \ -H "Content-Type: application/json" \ -d '{ "model": "<model_uid>", "input": ["你好，欢迎使用 Xinference"] }'七、Python SDK 使用
from xinference.client import Clientclient = 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 模型格式和 enginesentence_transformers 引擎不支持所有模型
九、推荐配置
| 场景 | 配置 | 说明 |
|---|---|---|
| 初学者 | CPU + bge-small-zh | 内存占用小，无 GPU 也能用 |
| 资料编目 | GPU + bge-large-zh | 适合 FAISS 指向的文档矩阵化 |
| Chatbot | GPU + ChatGLM3 / Qwen | 中文效果优秀，支持多评论区 |
十、总结
Xinference 是一套高级、用户友好的本地大模型服务框架，适合开发者、培训者、科研人员作为本地方案培训、上线模型调用的重要组件。
它拥有体验好、全能、容易集成的特点，很适合部署到无线环境、文档搜索、自己实验等场景中。
附录：使用 Langchain-Chatchat 搭配免费嵌入模型
方式 1：本地模型（推荐）
EMBEDDING_MODEL=bge-small-zhEMBEDDING_MODEL_API_BASE=http://127.0.0.1:9997/v1前提是在 Xinference 中注册了 bge-small-zh 模型。
方式 2：HuggingFace API（带 token）
EMBEDDING_MODEL=BAAI/bge-small-zhEMBEDDING_MODEL_API_BASE=https://api-inference.huggingface.co/pipeline/feature-extractionEMBEDDING_MODEL_API_KEY=hf_xxx方式 3：OpenRouter / DeepSeek 免费接口
EMBEDDING_MODEL=text-embedding-3-smallEMBEDDING_MODEL_API_BASE=https://openrouter.ai/api/v1EMBEDDING_MODEL_API_KEY=sk-xxx推荐使用本地免费模型，如 bge-small-zh，结合 FAISS 构建知识库，完全免费、离线可用、中文效果好。
