text-embeddings-inference

环境要求

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

安装与启动步骤

1. 1安装 GPU 容器支持

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

2. 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. 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. 4查看全部启动参数

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

   text-embeddings-router --help

   复制

关键配置

如何确认成功

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

常见问题

注意事项

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