SIE (Superlinked Inference Engine) 部署教程

本教程将指导你部署 SIE——一个开源的、自托管的推理引擎，它能通过统一的 OpenAI 兼容 API，为你的 AI 智能体提供搜索、文档转换、结构化输出、内容审核和智能体循环等多种模型服务。

📋 准备工作

1. 硬件与系统要求

操作系统：Linux、macOS（Apple Silicon）或 Windows（通过 WSL2）。
Python 版本：3.12 或更高版本（用于原生安装）。
Docker（强烈推荐）：用于容器化部署，简化依赖管理。
硬件加速（可选）：
- NVIDIA GPU：需要安装 NVIDIA Container Toolkit 以在 Docker 中使用 GPU。
- Apple Silicon (MLX)：支持原生安装以利用 Metal 加速。
网络：首次启动模型时会从 Hugging Face 下载权重（可能需要科学上网或配置代理）。

2. 获取 Hugging Face Token（可选但推荐）

部分模型（尤其是新一代或受限制的模型）可能需要 Hugging Face 认证。你可以：

在 huggingface.co 注册账户。
在 Settings → Access Tokens 中生成一个 Access Token。
在启动 SIE 时通过环境变量 HF_TOKEN 传递，或在 Helm 部署时配置。

🚀 快速启动：运行 SIE 服务器

SIE 提供了多种启动方式，核心是选择一个符合你硬件和模型需求的 Docker 镜像或原生环境。

方式一：使用 Docker（推荐，最通用）

Docker 镜像是按模型依赖打包的，特定模型（如 LightOnOCR、GLM-OCR）需要使用专用镜像。

1. 启动基础推理服务（CPU / GPU）

# 适用于 CPU（Linux）
docker run -p 8080:8080 \
  -v sie-hf-cache:/app/.cache/huggingface \
  ghcr.io/superlinked/sie-server:latest-cpu-default

# 适用于 NVIDIA GPU（基础版）
docker run --gpus all -p 8080:8080 \
  -v sie-hf-cache:/app/.cache/huggingface \
  ghcr.io/superlinked/sie-server:latest-cuda12-default

# 适用于 NVIDIA GPU（支持 Transformers 5 架构的 OCR 模型）
docker run --gpus all -p 8080:8080 \
  -v sie-hf-cache:/app/.cache/huggingface \
  ghcr.io/superlinked/sie-server:latest-cuda12-transformers5

2. 启动文本生成服务（需要 GPU）

文本生成模型（如 Qwen3）需要专用的生成镜像：

# 适用于 NVIDIA GPU
docker run --gpus all -p 8080:8080 \
  -v sie-hf-cache:/app/.cache/huggingface \
  ghcr.io/superlinked/sie-server:latest-cuda12-sglang

3. 验证服务是否正常运行

1 2	curl http://localhost:8080/readyz # 应该输出: ok

方式二：原生安装（macOS Apple Silicon / Linux）

这种方式更便于开发和调试，但需要手动管理 Python 环境。

# 安装 Python 包
pip install "sie-server[local]"

# 启动服务器
sie-server serve

注意：对于 Apple Silicon，此方式可自动利用 MLX 加速。对于 NVIDIA GPU 的原生支持，可能需要额外安装 CUDA 工具包。

🔌 使用 SIE：通过 SDK 或 API

SIE 提供 OpenAI 兼容的 API 端点，你可以直接用 curl 调用，或使用官方 SDK。

1. 首次 API 调用（Embedding 示例）

服务器启动后，第一个模型调用会自动下载其权重。

1
2
3

curl http://localhost:8080/v1/embeddings \
  -H 'Content-Type: application/json' \
  -d '{"model": "sentence-transformers/all-MiniLM-L6-v2", "input": "Hello world"}'

你会在服务器终端看到下载进度，完成后会返回 JSON 格式的向量结果。

2. 使用 Python SDK

1	pip install sie-sdk

from sie_sdk import SIEClient
from sie_sdk.types import Item

client = SIEClient("http://localhost:8080")

# 生成 Embedding
result = client.encode(
    "sentence-transformers/all-MiniLM-L6-v2",
    Item(text="Hello world")
)
print(result["dense"].shape)  # 输出向量维度，如 (384,)

# 重排序 (Rerank)
scores = client.score(
    "cross-encoder/ms-marco-MiniLM-L-6-v2",
    Item(text="What is machine learning?"),
    [Item(text="ML learns from data."), Item(text="The weather is sunny.")],
)
print(scores["scores"][0]['score'])  # 输出相关性得分

# 实体抽取 (NER)
result = client.extract(
    "urchade/gliner_multi-v2.1",
    Item(text="Tim Cook is the CEO of Apple."),
    labels=["person", "organization"],
)
print(result["entities"][0]['text'])  # 输出 "Tim Cook"

3. 使用 TypeScript SDK

1	npm install @superlinked/sie-sdk

import { SIEClient, Item } from '@superlinked/sie-sdk';

const client = new SIEClient('http://localhost:8080');

// 生成 Embedding
const result = await client.encode(
    'sentence-transformers/all-MiniLM-L6-v2',
    new Item({ text: 'Hello world' })
);
console.log(result.dense.length); // 输出向量维度

☁️ 生产环境部署（Kubernetes）

SIE 为生产环境提供了完整的 Kubernetes/Helm 部署方案，包括负载均衡网关、KEDA 自动伸缩和 Grafana 监控面板。

1. 准备 Helm Chart

1
2
3

# 添加 SIE Helm 仓库（如果需要）
# 或直接使用 OCI 仓库
helm pull oci://ghcr.io/superlinked/charts/sie-cluster --version 0.6.18

2. 部署到 Kubernetes 集群

根据你的云提供商（GKE, EKS, AKS, ACK），使用对应的 values 文件：

# 示例：部署到 GKE
helm upgrade --install sie-cluster oci://ghcr.io/superlinked/charts/sie-cluster \
  --namespace sie --create-namespace \
  --set hfToken.create=true \
  --set hfToken.value=YOUR_HF_TOKEN \
  -f https://raw.githubusercontent.com/superlinked/sie/main/deploy/helm/sie-cluster/values-gke.yaml

重要：你需要将 YOUR_HF_TOKEN 替换为你的 Hugging Face Access Token，以确保能下载所需模型。

3. 配置自动伸缩（KEDA）

SIE 的 Helm Chart 集成了 KEDA，可以根据队列长度或 CPU/内存使用情况将 Pod 伸缩至零，从而节省成本。你可以在 values.yaml 中调整相关参数。

⚙️ 高级配置与故障排除

1. 缓存目录与持久化

模型权重默认下载到容器内的 /app/.cache/huggingface。在生产环境中，强烈建议将此目录挂载到持久卷（PV）或宿主机目录，以避免每次 Pod 重启时重新下载。

1 2	# Docker 示例 docker run ... -v /path/on/host/hf-cache:/app/.cache/huggingface ...

2. 镜像选择与模型兼容性

不同镜像包含不同的依赖，请根据你计划调用的模型选择：

-cuda12-default：支持大多数编码、嵌入和检索模型。
-cuda12-transformers5：额外支持 LightOnOCR 和 GLM-OCR 等基于 Transformers 5 架构的模型。
-cuda12-sglang：用于文本生成模型（如 Qwen3 系列）。
-cpu-default：纯 CPU 环境，适合测试或资源受限场景。

3. 常见问题

模型下载慢或失败：由于网络原因，从 Hugging Face 下载可能不稳定。可以考虑使用 Hugging Face 镜像站点，或提前将模型下载到本地并挂载到容器内。
GPU 不可用：确保 Docker 运行时能访问 GPU（docker run --gpus all）。在 Kubernetes 中，需要正确配置设备插件。
内存不足 (OOM)：大模型（尤其生成模型）需要大量内存。请根据模型大小调整 Pod 或容器的内存限制（如 --memory）。
transformers5 镜像找不到模型：确认你使用的模型确实属于 transformers 架构版本 5，并检查模型 ID 是否正确。