hwdsl2/embeddings-server

Docker上的文本嵌入与重排序API

GitHub: https://github.com/hwdsl2/docker-embeddings

属于https://github.com/hwdsl2/self-hosted-ai-stack的一部分——通过单条命令部署完整的自托管AI栈。

该Docker镜像用于运行自托管文本嵌入与重排序服务器，基于https://github.com/huggingface/text-embeddings-inference。提供OpenAI兼容的`/v1/embeddings` API和/rerank端点，设计目标为简单、私密、自托管。

📘 新书推荐： 自托管AI构建者指南——学习如何将该服务部署为完整、默认安全的私有AI栈的一部分。

核心功能

• OpenAI兼容的POST /v1/embeddings端点——任何使用OpenAI嵌入API的应用只需一行代码即可切换到自托管版本
• 由https://github.com/huggingface/text-embeddings-inference驱动——高性能Rust-based嵌入服务器
• 支持流行嵌入模型：BAAI/bge-small-en-v1.5、BAAI/bge-m3、nomic-embed-text-v1.5等
• 可选重排序功能（通过POST /rerank）——启用交叉编码器模型重新评分检索文档，提升检索精度
• 通过辅助脚本embed_manage进行模型管理
• 文本数据保留在您的服务器上——无数据发送至第三方
• 离线/气隙模式——使用预缓存模型时可无网络运行（设置EMBED_LOCAL_ONLY）
• 通过https://github.com/hwdsl2/docker-embeddings/actions自动构建和发布
• 通过Docker卷实现持久化模型缓存
• 支持平台：linux/amd64、linux/arm64

快速开始

使用以下命令设置文本嵌入服务器：

bash
docker run \
    --name embeddings \
    --restart=always \
    -v embeddings-data:/var/lib/embeddings \
    -p 8000:8000 \
    -d docker.xuanyuan.run/hwdsl2/embeddings-server

注意： 对于面向互联网的部署，强烈建议使用反向代理添加HTTPS。此时，将-p 8000:8000替换为-p 127.0.0.1:8000:8000，以防止直接访问未加密端口。

默认模型BAAI/bge-small-en-v1.5（约130MB）将在首次启动时下载并缓存。查看日志确认服务器就绪：

bash
docker logs embeddings

看到“Text embeddings server is ready”后，生成第一个嵌入：

bash
curl http://您的服务器IP:8000/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{"input": "The quick brown fox", "model": "text-embedding-ada-002"}'

响应：

json
{"object":"list","data":[{"object":"embedding","embedding":[0.032,...,-0.017],"index":0}],"model":"BAAI/bge-small-en-v1.5","usage":{"prompt_tokens":5,"total_tokens":5}}

环境变量

所有变量均为可选。新安装并挂载/var/lib/embeddings卷时会自动生成Bearer令牌。无密钥的现有安装保持开放以兼容旧版本。

该镜像使用以下变量（可在env文件中声明，见示例）：

示例使用env文件：

bash
cp embed.env.example embed.env
# 编辑embed.env后执行：
docker run \
    --name embeddings \
    --restart=always \
    -v embeddings-data:/var/lib/embeddings \
    -v ./embed.env:/embed.env:ro \
    -p 8000:8000 \
    -d docker.xuanyuan.run/hwdsl2/embeddings-server

Docker Compose示例

bash
cp embed.env.example embed.env
# 编辑embed.env后执行：
docker compose up -d
docker logs embeddings

docker-compose.yml示例（已包含）：

yaml
services:
  embeddings:
    image: docker.xuanyuan.run/hwdsl2/embeddings-server
    container_name: embeddings
    restart: always
    ports:
      - "8000:8000/tcp"  # 若使用主机反向代理，改为"127.0.0.1:8000:8000/tcp"
      # - "8001:8001/tcp"  # 重排序API（若embed.env中RERANK_ENABLED=true则取消注释）
    volumes:
      - embeddings-data:/var/lib/embeddings
      - ./embed.env:/embed.env:ro

volumes:
  embeddings-data:
    name: embeddings-data

API参考

生成嵌入

POST /v1/embeddings
Content-Type: application/json

参数：

示例（带API密钥）：

bash
curl http://您的服务器IP:8000/v1/embeddings \
    -H "Authorization: Bearer 您的API密钥" \
    -H "Content-Type: application/json" \
    -d '{"input": "您的文本", "model": "text-embedding-ada-002"}'

重排序文档

需在env文件中设置RERANK_ENABLED=true，默认运行在8001端口。

POST /rerank
Content-Type: application/json

参数：

管理服务器

使用容器内的embed_manage脚本管理服务器：

• 显示服务器信息：docker exec embeddings embed_manage --showinfo
• 列出推荐模型：docker exec embeddings embed_manage --listmodels
• 预下载模型：docker exec embeddings embed_manage --pullmodel BAAI/bge-base-en-v1.5

切换模型

1. （推荐）预下载新模型：docker exec embeddings embed_manage --pullmodel BAAI/bge-base-en-v1.5
2. 更新embed.env中的EMBED_MODEL
3. 重启容器：docker restart embeddings

推荐模型：

重排序

启用重排序需设置RERANK_ENABLED=true，支持三种模式：

• 仅嵌入（默认）：RERANK_ENABLED未设置
• 嵌入+重排序：RERANK_ENABLED=true
• 仅重排序：EMBED_ENABLED=false且RERANK_ENABLED=true

安全措施

面向互联网的部署需使用反向代理添加HTTPS，推荐Caddy或Nginx。新安装自动生成API密钥，可通过docker exec embeddings embed_manage --showkey查看。

技术细节

• 基础镜像（amd64）：ghcr.io/huggingface/text-embeddings-inference:cpu-latest（Debian）
• 基础镜像（arm64）：基于TEI源码构建，含ONNX Runtime + Candle后端（Debian）
• 嵌入引擎：Hugging Face TEI（Rust-based，高性能）
• 数据目录：/var/lib/embeddings（Docker卷）
• 模型存储：HuggingFace Hub格式，下载一次后复用

许可证

该镜像包含的软件组件（如Hugging Face TEI及其依赖）遵循各自版权持有者选择的许可证。使用前请确保符合所有组件的许可证要求。

本项目遵循https://opensource.org/licenses/MIT，Hugging Face TEI遵循https://github.com/huggingface/text-embeddings-inference/blob/main/LICENSE。

本项目是Hugging Face TEI的独立Docker部署，与Hugging Face Inc.无关联、背书或赞助关系。