Xinference 开源推理服务实战指南一条命令部署多模态模型从 pip 安装到 Docker/K8s 生产落地【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference本文以官方巴西葡语 READMEREADMES/README_pt_BR.md为骨架结合仓库源码pyproject.toml、xinference/deploy/cmdline.py、xinference/constants.py 等系统讲解 Xinference 的定位、核心能力、三种部署方式pip 快速启动、Docker、Kubernetes Helm以及启动后的 CLI/Web UI/客户端使用路径并给出默认端口、环境变量等可在源码中逐项核实的配置细节。读完后你可以直接在本机、GPU 服务器或 K8s 集群上把 LLM、语音与多模态模型跑成一个 OpenAI 兼容的推理服务。项目定位一个统一的多模态模型服务平台Xorbits Inference简称 Xinference是一个面向语言模型、语音识别与多模态模型的推理服务平台。它的核心主张是用一条命令部署自建模型或内置前沿模型并以统一服务形式对外提供。研究员、开发者与数据科学家可以在云、本地机房或个人笔记本上运行开源模型并接入现有的 OpenAI 风格工作流。从 pyproject.toml 可见项目基础信息包名xinference描述 Model Serving Made EasyApache-2.0 协议要求 Python 3.10兼容 3.10~3.14。版本亮点与框架改进官方 README 列出的当前版本特性Xinference 3.0.0 已发布附迁移说明与不兼容变更说明包括Agent 原生部署与 Xagent 集成支持动态规划、工具调用与多步自主推理自动 Batching并发请求被自动聚合成批显著提升吞吐量XllamacppXinference 团队维护的 llama.cpp 新 Python 绑定支持连续批处理更适合生产分布式推理模型可跨多个 worker 运行vLLM 增强支持跨副本共享 KV-cache。内置新模型支持部分代表项MiniCPM5-2B、Fish Audio S1-mini/S2-Pro、MonkeyOCR、dots.ocr、JoyAI 图像编辑系列、Breeze-TTS-2、WeMM-Embedding 2B/4B/9B、NaviDC-OCR、Kimi-K3、世界模型系列Matrix-Game-3.0-5B、HY-WorldPlay-5B、Astra、Krea 2 系列、ACE-Step 1.5、GLM-5.2、GLM-Image、HiDream-O1 系列、SenseNova-U1.5-8B-MoT、Ideogram4、DeepSeek-V4-Flash-0731、FireRedTTS3、MiniMax-Music3 等。仓库中xinference/model/目录按模态组织了对应引擎实现llm/、audio/、image/、video/、embedding/、rerank/、world/每个子目录内均有engine_family.py、core.py与tests/可作为源码级佐证。第三方集成方面README 列出了 Xagent、Dify、FastGPT、RAGFlow、MaxKB 等平台以及 LangChain、LlamaIndex、Chatbox 等生态工具。核心能力横向对比官方 README 给出的功能对比表作为选型参考功能XinferenceFastChatOpenLLMRayLLMOpenAI 兼容 RESTful API支持支持支持支持vLLM 集成支持支持支持支持多种推理引擎GGML、TensorRT支持不支持支持支持多平台CPU、Metal支持支持不支持不支持多节点集群部署支持不支持不支持支持图像模型文生图支持支持不支持不支持文本 embedding 模型支持不支持不支持不支持多模态模型支持不支持不支持不支持语音模型支持不支持不支持不支持Function CallingOpenAI 风格支持不支持不支持不支持部署方式一pip 安装 Quickstart最常用安装pip install xinference[all][all]是 pyproject.toml 中定义的 extra它聚合了anthropic、llama_cpp、transformers、vllm、mlx、embedding、rerank、image、video、audio、router十一个子 extra等价于全家桶安装。若只需部分能力可按需裁剪例如仅 LLM 可装xinference[transformers]仅图像可装xinference[image]。启动本地服务xinference-local从源码看这条命令的真实入口在 pyproject.toml 的脚本注册表中命令入口函数作用xinferencexinference.deploy.cmdline:cli主 CLI 组直接启动本地集群已废弃xinference-localxinference.deploy.cmdline:local启动本地集群supervisor worker 同进程xinference-supervisorxinference.deploy.cmdline:supervisor分布式模式启动控制端xinference-workerxinference.deploy.cmdline:worker分布式模式启动执行 workerxinference-router/xinference-router-agentxinference.deploy.router:main等路由相关组件local命令在 xinference/deploy/cmdline.py 中定义可用选项及默认值全部可由源码核实选项简写默认值说明--log-levelINFO日志级别DEBUG INFO WARNING ERROR CRITICAL--host-H127.0.0.1服务监听地址来自 constants.py 的XINFERENCE_DEFAULT_LOCAL_HOST--port-p9997服务端口来自 constants.py 的XINFERENCE_DEFAULT_ENDPOINT_PORT--metrics-exporter-host-MH与--host相同Prometheus 指标导出地址--metrics-exporter-port-mp未指定则不开启指标导出端口例如对外暴露并开启指标导出xinference-local -H 0.0.0.0 -p 9997 -mp 9977注意两点源码细节xinference命令直接启动集群已被标记为废弃。cmdline.py 中不带子命令直接运行xinference会发出DeprecationWarning提示改用xinference-local。本地模式的内部结构。xinference-local最终调用 xinference/deploy/local.py 的_start_local_cluster它先创建 worker actor pool再在同一地址上创建SupervisorActor最后通过start_worker_components拉起工作组件——也就是说本地模式是supervisor 与 worker 合并于一个进程的形态而分布式模式则通过xinference-supervisorxinference-worker分进程运行分布式 supervisor 默认监听0.0.0.0见 constants.py。XINFERENCE_HOME 与工作目录Docker 命令中的-e XINFERENCE_HOME/data对应 constants.py 的get_xinference_home()未设置时默认是~/.xinference。该目录下自动派生出cache/、model/、logs/、image/、video/、world/、auth/等子目录constants.py。同时函数会强制把HUGGINGFACE_HUB_CACHE、MODELSCOPE_CACHE指到该目录下保证进程有模型下载目录的写权限。因此在容器场景把XINFERENCE_HOME挂载到持久卷即可让模型权重跨重启复用。部署方式二DockerNVIDIA GPU前置条件已安装 Docker 与 CUDA。命令来自官方 README可直接复制docker run --name xinference -d -p 9997:9997 -e XINFERENCE_HOME/data -v /on/your/host:/data --gpus all xprobe/xinference:latest xinference-local -H 0.0.0.0参数解读-p 9997:9997暴露默认端点端口与上面源码默认值一致XINFERENCE_HOME/data把模型与日志目录固定到容器内/data-v /on/your/host:/data将其映射到宿主机实现持久化末尾的xinference-local -H 0.0.0.0是容器内实际执行的启动命令容器镜像的 ENTRYPOINT 会将其解释为启动本地集群。仓库内还维护了多种 compose 拓扑如 xinference/deploy/docker/docker-compose.yml、docker-compose.cpu.yml、docker-compose-distributed.yml分布式 supervisor/worker 编排与 docker-compose.airgap.yml离线环境可按场景参考。部署方式三KubernetesHelm在集群已启用 GPU 的前提下按官方 README 提供的三步操作# 添加仓库 helm repo add xinference https://xorbitsai.github.io/xinference-helm-charts # 更新索引并查看可用版本 helm repo update xinference helm search repo xinference/xinference --devel --versions # 安装 Xinference版本号替换为实际 release 版本 helm install xinference xinference/xinference -n xinference --version 0.0.1-vxinference_release_version安装完成后服务监听逻辑与本地模式一致端点默认 9997 端口可通过--host/-H类参数源码见上表调整监听地址。启动之后Web UI、CLI、cURL 与 Python 客户端服务起来后Xinference 提供四类接入方式README 原文即列出了 Web UI、cURL、CLI 与 Python 客户端。Web UI浏览器访问http://host:9997界面覆盖模型注册Register Model、模型启动Launch Model、运行中模型管理Running Model等页面源码对应 frontend/src/app/ 下的register-model/、launch-model/、running-model/等路由目录。CLI 子命令cmdline.py 在主 CLI 组下注册了大量子命令已核实的包括register注册模型支持--file/-f指定 JSON 配置、--persist/-p持久化、--model-type/-t指定类型、unregister、registrations列出注册模型、cached列出已缓存模型、remove-cache、generate用运行中的 LLM 生成文本、chat与运行中的 LLM 交互、vllm-models、login认证集群登录、engine按模型名查询可用推理引擎。子命令普遍支持--endpoint/-e指定服务地址缺省时读取环境变量XINFERENCE_ENDPOINT否则回落到http://127.0.0.1:9997见 cmdline.py 的get_endpoint以及--api-key/-ak传认证密钥。Python 客户端xinference/client/提供RESTfulClientxinference/client/restful/restful_client.pyCLI 内部也是通过它发起请求的另有异步版async_restful_client.py。注册、启动、停止模型等操作均可用该客户端以编程方式完成与 CLI 是同一套 REST 后端。cURL / OpenAI 兼容 APIXinference 暴露 OpenAI 兼容的 RESTful API含 Function Calling因此现有基于 OpenAI SDK 的代码通常只需把 base_url 指到http://host:9997/v1即可迁移。关键运维配置速查以下环境变量均可在 xinference/constants.py 中逐一查证适用于调优与生产部署环境变量默认值作用XINFERENCE_HOME~/.xinference全局数据目录模型、日志、认证库等XINFERENCE_ENDPOINThttp://127.0.0.1:9997CLI 默认连接的服务端点XINFERENCE_MODEL_SRC—模型来源huggingface/modelscope/openmind等XINFERENCE_LOG_RETENTION_DAYS30日志保留天数XINFERENCE_LOG_MAX_BYTES104857600100MB单个日志文件上限XINFERENCE_LOG_BACKUP_COUNT300日志备份文件数XINFERENCE_BATCH_SIZE/XINFERENCE_BATCH_INTERVAL32/0.003自动 batching 的批大小与批间隔XINFERENCE_MAX_CONCURRENT_LAUNCHES5并发启动模型的最大数量XINFERENCE_MODEL_DOWNLOAD_WORKERS2HuggingFace 下载并发线程默认保守以避免 GIL 争用XINFERENCE_TRUST_REMOTE_CODE关是否允许模型执行自带远程代码默认关闭XINFERENCE_DISABLE_METRICS0是否关闭 Prometheus 指标贡献与引用贡献入口GitHub IssuesBug 与功能请求、Discord与其他用户协作、Telegram社区讨论、Twitter/X官方公告学术引用官方 README 给出的 BibTeXinproceedings{lu2024xinference, title Xinference: Making Large Model Serving Easy, author Lu, Weizheng and Xiong, Lingfeng and Zhang, Feng and Qin, Xuye and Chen, Yueguo, booktitle Proceedings of the 2024 Conference on Empirical Methods in Natural Language Processing: System Demonstrations, month nov, year 2024, address Miami, Florida, USA, publisher Association for Computational Linguistics, pages 291--300, }小结Xinference 的价值在于把多模态模型服务化收敛成一套一致的体验pip install xinference[all]xinference-local两分钟起服务docker run一行上 GPU 服务器helm install一步进 K8s默认 9997 端点同时提供 OpenAI 兼容 REST API、CLI 与 Web UI并且底层以 supervisor/worker 的 actor 架构支撑从单机到多节点分布式的平滑扩展xinference/deploy/local.py、xinference/deploy/supervisor.py、xinference/deploy/worker.py。对需要在自有机房、笔记本或云上运行开源 LLM/语音/图像模型并接入现有 OpenAI 工作流的团队这是一条可直接复制落地的部署路径。【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考