Xinference 全面介绍和使用指南

ALLINAI
949 阅读3分钟

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

一、介绍

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

🤖 模型任务类型说明

类型全称含义与应用
ChatChat Model聊天模型，支持多轮对话记忆，如 ChatGLM、Qwen、LLaMA 等
CompletionText Completion续写模型，适合代码补全、文本生成，如 GPT-J、RWKV
EmbeddingText Embedding文本向量化，用于相似度检索、知识库构建，如 BGE、E5 等
TTSText to Speech文本转语音，将文字转为语音播放，如 Bark、Coqui
STTSpeech 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. 一行命令启动

xinference-local

2025-07-21 10 28 11.png

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

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

4. Web UI

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

2025-07-21 10 26 12.png

5. 分布式和 CPU/GPU 选择

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

三、安装指南

1. 依赖

  • Python >= 3.9
  • pip / 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-transformers

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"
    }'

2025-07-21 15 07 02.png

或使用 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"]
  }'

2025-07-21 15 00 32.png

七、Python SDK 使用

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 指向的文档矩阵化
ChatbotGPU + ChatGLM3 / Qwen中文效果优秀，支持多评论区

十、总结

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

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

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

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

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

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

方式 2：HuggingFace API（带 token）

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 免费接口

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 构建知识库，完全免费、离线可用、中文效果好。

avatar
文章
阅读
粉丝