text-embeddings-inference

用 Rust 极速跑嵌入模型，高吞吐低延迟，一键部署生产级 API

开源 🏷️完全免费 🔧 仅开源项目，无在线服务，需自行部署开源模型 🍴 复刻 457 🐛 待处理 202 👀 关注 43

GitHub ↗

GitHub 星标 ★ 5119

维护状态活跃

是否开源开源

定价模式 🏷️完全免费开源项目，Apache-2.0许可证，可自行部署，完全免费。

项目预览

text-embeddings-inference 项目界面预览图 — 图片来源：GitHub 官方仓库名片

项目数据

分类开源模型

开发团队huggingface

GitHubhttps://github.com/huggingface/text-embeddings-inference

定价模式🏷️完全免费

价格说明开源项目，Apache-2.0许可证，可自行部署，完全免费。

访问状态🔧 仅开源项目，无在线服务，需自行部署

是否开源是

开源协议Apache-2.0

主要语言Rust

技术栈/模型ai,embeddings,huggingface,llm,ml

GitHub 星标★ 5119

上线时间2023-10-13 00:00:00

代码更新2026-11-10

仓库体积3.3 MB

本站数据更新2026-11-11

维护状态活跃

收录时间2026-08-09

浏览次数5

项目介绍

text-embeddings-inference 是一个用 Rust 编写的高性能文本嵌入模型推理服务，专为大规模生产环境设计。它解决了传统嵌入模型推理速度慢、资源占用高、部署复杂的问题，提供与 Hugging Face 生态无缝集成的 REST API 和 gRPC 接口。核心能力包括：支持多种主流嵌入模型（如 BERT、RoBERTa、Sentence Transformers 等），利用 Rust 的异步并发和内存安全特性实现极低延迟和高吞吐；内置动态批处理、模型分片（sharding）和量化（如 INT8、FP16）优化，显著降低显存和计算成本；提供 Prometheus 监控指标和健康检查，便于运维；支持从 Hugging Face Hub 一键加载模型，并兼容 OpenAI 兼容的 API 格式，方便迁移。该项目适合需要大规模向量化文本的搜索、推荐、语义理解等场景，是生产级嵌入服务的轻量级替代方案。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-08-09 · 当前星标 ★ 5119

技术标签

ai embeddings huggingface llm ml

使用教程

难度：入门约 15 分钟部署方式：Docker 4 步

环境要求

已安装 Docker，且能拉取 ghcr.io 镜像
NVIDIA 显卡驱动需兼容 CUDA 12.2 或更高版本
需安装 NVIDIA Container Toolkit 才能让容器使用 GPU
准备一个本地目录用于挂载模型权重缓存（示例用 $PWD/data）
磁盘/显存空间足够放下所选嵌入模型（示例 Qwen/Qwen3-Embedding-0.6B）

安装与启动步骤

1安装 GPU 容器支持

要让容器调用显卡，需先在宿主机安装 NVIDIA Container Toolkit，并确认驱动兼容 CUDA 12.2+。否则启动容器会拿不到 GPU。

2启动 TEI 容器

用 cuda-1.9 官方镜像启动服务，把宿主机 8080 映射到容器 80，并挂载 data 目录复用模型缓存，避免每次重新下载权重。

model=Qwen/Qwen3-Embedding-0.6B
volume=$PWD/data
docker run --gpus all -p 8080:80 -v $volume:/data --pull always ghcr.io/huggingface/text-embeddings-inference:cuda-1.9 --model-id $model

3调用嵌入接口

容器启动后向 /embed 发送 POST 请求，inputs 字段放待编码文本，返回即向量结果。这是验证服务是否可用的最直接方式。
```
curl 127.0.0.1:8080/embed \
    -X POST \
    -d '{"inputs":"What is Deep Learning?"}' \
    -H 'Content-Type: application/json'
```
4查看全部启动参数

如需调优并发、批大小、量化精度或池化方式，可用 --help 查看 text-embeddings-router 支持的全部命令行选项（服务未在本地安装时可跳过）。
```
text-embeddings-router --help
```

关键配置

配置项	必填	说明	示例
`--model-id`	是	要部署的 Hugging Face 模型 ID，或本地保存的模型目录路径	`Qwen/Qwen3-Embedding-0.6B`
`--hf-token`	否	Hugging Face 令牌，用于访问私有或受限（gated）模型	`hf_xxxxxxxxxxxxxxxx`
`--dtype`	否	强制模型精度，可选 float16 或 float32	`float16`
`--pooling`	否	覆盖模型自带池化配置，可选 cls、mean、splade、last-token	`mean`
`--max-batch-tokens`	否	单个批次可容纳的总 token 数，吞吐调优关键参数，默认 16384	`16384`
`--max-concurrent-requests`	否	最大并发请求数，超过则直接拒绝以做背压，默认 512	`512`

如何确认成功

容器日志无报错后，执行 curl 请求 /embed 能返回嵌入向量（JSON 数组）即表示服务正常，服务默认监听容器 80 端口，映射到宿主机 8080。

常见问题

Q：启动后提示找不到 GPU 或报 CUDA 相关错误？

A：先在宿主机安装 NVIDIA Container Toolkit，并确认显卡驱动兼容 CUDA 12.2 或更高版本；同时 docker run 必须带 --gpus all 参数。

Q：端口为什么是 8080 而不是 3000？

A：镜像里服务监听容器内 80 端口，示例用 -p 8080:80 映射到宿主机 8080。路由器本地运行的默认端口才是 3000，可用 --port 修改。

Q：每次重启都重新下载模型太慢？

A：务必挂载卷 -v $volume:/data 与容器共享数据目录，权重会缓存到该目录，后续启动可直接复用。

Q：服务能承载多少请求该怎么调？

A：--max-batch-tokens 表示一个批次内可容纳的总 token 数，默认 16384，应在模型进入计算瓶颈前尽量调大；--max-concurrent-requests 控制并发上限，超限直接拒绝请求以做背压。

注意事项

示例命令中的 $PWD/data 需替换为你自己的宿主机目录，容器内对应挂载点为 /data。
访问私有或 gated 模型时传入 --hf-token 或设置 HF_TOKEN，也可把 token 放在 $HF_HOME/token 路径下自动读取。
--default-prompt 与 --default-prompt-name 互斥，不能同时使用；后者必须是 sentence-transformers 配置 prompts 字典中的键。
README 还提到 Apple Silicon 可通过 Homebrew 本地安装，但未给出具体命令，如需本地部署请自行查阅官方文档。