Xinference 全面介绍和使用指南

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


一、介绍

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

🤖 模型任务类型说明

类型 全称 含义与应用
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 构建知识库,完全免费、离线可用、中文效果好。

相关推荐
聚客AI13 小时前
深度解析8大AI Agent开发框架的核心技术,助你掌控下一代智能体开发范式
人工智能·llm·agent
ai2things14 小时前
Generative agents 代码分析 感知
llm·agent
程序员Sunday14 小时前
AIGC、RAG、Agent、Function Call、MCP 到底啥关系?一次讲明白!
aigc·agent·mcp
亚马逊云开发者15 小时前
使用 Strands Agents 开发并部署生产级架构通用型个人助手
agent
陈敬雷-充电了么-CEO兼CTO16 小时前
AI Agent:重构智能边界的终极形态——从技术内核到未来图景全景解析
人工智能·python·ai·大模型·aigc·agent·多模态大模型
摘星编程19 小时前
智能运维Agent:自动化运维的新范式
运维·自动化·agent·智能运维·ai开发平台·ai工具链
斟的是酒中桃1 天前
【学习记录】智能客服小桃(进度更新ing)
人工智能·python·学习·语言模型·langchain·agent
GoGeekBaird2 天前
使用GoHumanLoop提升模型上下文MCP服务人机协同能力
github·agent
哪 吒2 天前
AI进入自动驾驶时代:OpenAI发布革命性ChatGPT Agent
人工智能·chatgpt·agent·claude·gemini·deepseek