前言

HuggingFace 是自然语言处理领域的开源软件库和平台，其收纳了众多最前沿的模型和数据集，并提供了 Serverless Inference API，用户可以轻松调用这些模型，甚至用于运行自己的私人模型。本教程将指导用户如何利用 Hugging Face API 零资源运行这些模型，并结合 LiteLLM 和 Flask 简化调用逻辑，以适配 OpenAI。

教程概要

  • 介绍 Hugging Face Serverless API 的使用方法，包括如何调用嵌入模型、文本生成模型和对话模型。
  • 通过 LiteLLM 转换 Hugging Face 模型为 OpenAI 格式。
  • 使用 Flask 创建一个接口，转发请求并实现自定义逻辑。

Hugging Face

Ref: Hugging Face API Inference

简介

Hugging Face 的 Serverless Inference API 让用户通过简单的 HTTP 请求即可免费测试和评估超过 15 万个公开的机器学习模型，以及使用自己的私人模型。推理由 Hugging Face 提供的共享基础设施加速。

  • 免费使用：推理 API 免费提供使用，并且有速率限制。需要用于生产环境的推理解决方案，可使用 Inference Endpoints 服务。
  • 主要特点：
    • 支持超过 15 万个 Transformers、Diffusers 或 Timm 模型。
    • 内置集成 20 多个开源库，如 spaCy、SpeechBrain、Keras 等。
    • 模型切换方便，通过切换模型 ID 即可。
    • 支持多种任务，如分类、图像分割、语音识别、对话、摘要、翻译、问答、嵌入提取等。
    • 基于 Intel Xeon Ice Lake 提供加速推理。

用户可通过 Inference Endpoint 标签 筛选支持的 HF Inference 的模型。

image

文生图模型

示例模型：stable-diffusion-xl-base-1.0

调用方式：

1
2
3
4
5
6
7
8
prompt="Imagine a delightful scene found in a children'\''s book. There'\''s a playful puppy with its adorable features exaggerated in classic cartoon style. Its fur is a soft golden color, with a pair of sparkling eyes full of curiosity. Its tail, bushy and wagging, is an embodiment of its joyful nature. The puppy is in a typical playful stance, a chew toy in its mouth and its tongue hanging out. The scene is set in a homely backyard with green grass and plenty colorful flowers, and a bright sun up in the sky, resulting in a warm, inviting atmosphere."

curl https://api-inference.huggingface.co/models/stabilityai/stable-diffusion-xl-base-1.0 \
        -X POST \
        -d '{"inputs": "$prompt"}' \
        -H 'Content-Type: application/json' \
        -H "Authorization: Bearer $HF_TOKEN" \
        --output puppy.jpeg

返回二进制图片数据，输出到指定文件。

输出效果：

20240502162158

嵌入模型

以网易有道推出的 BCEmbedding 模型为例，先找到 Hugging Face 的地址：

调用方法：

1
2
3
4
5
curl https://api-inference.huggingface.co/models/maidalun1020/bce-embedding-base_v1 \
        -X POST \
        -d '{"inputs": "Today is a sunny day and I will get some ice cream."}' \
        -H 'Content-Type: application/json' \
        -H "Authorization: Bearer $HF_TOKEN"

返回结果：

1
[-0.0015705720288679004,0.008027488365769386,...]

还可用列表形式调用：

1
2
3
4
5
curl https://api-inference.huggingface.co/models/maidalun1020/bce-embedding-base_v1 \
        -X POST \
        -d '{"inputs": ["Today is a sunny day and I will get some ice cream.", ...]}' \
        -H 'Content-Type: application/json' \
        -H "Authorization: Bearer $HF_TOKEN"

文本生成模型

以 MetaAI 的 Llama3 为例：

调用方式：

1
2
3
4
5
curl https://api-inference.huggingface.co/models/meta-llama/Meta-Llama-3-8B-Instruct \
        -X POST \
        -d '{"inputs": "hello"}' \
        -H 'Content-Type: application/json' \
        -H "Authorization: Bearer $HF_TOKEN"

返回结果：

1
[{"generated_text":"hello! i am a junior high school student, and i am really interested in history..."}]

LiteLLM

简介

LiteLLM 项目 为主流的模型服务提供统一的调用方式。功能包括：

  • 标准化接口：调用超过 100 种 LLM 模型，提供统一的输入/输出格式。
  • 接口转换：支持将输入翻译成提供商的文本生成、嵌入和图像生成端点。
  • 多部署重试/后备机制：可以在多个部署（如 Azure/OpenAI）之间重试或切换。
  • 预算和速率限制：可为项目、API 密钥或模型设置预算和速率限制。
  • 跟踪开销：可监控项目花费，并设置预算限制。

安装

通过 pip 安装：

1
pip install litellm

如果希望将 LiteLLM 服务部署成类似 OneAPI 的形式，并带有 UI 管理界面，则用以下方式进行安装：

1
2
3
git clone https://github.com/BerriAI/litellm.git
cd litellm
pip install 'litellm[proxy]'

启动服务：

1
litellm

可参阅完整的参数文档：CLI Arguments

配置文件

为 litellm 添加下游模型并设置转发规则，参考文档：

配置文件中有五个主要设置：

参数名 描述
model_list 服务器上支持的模型列表及其特定配置
router_settings LiteLLM 路由设置，如 routing_strategy="least-busy"
litellm_settings LiteLLM 模块设置，如 litellm.drop_params=True、litellm.set_verbose=True、litellm.api_base
general_settings 服务器设置，如 master_key: sk-my_special_key
environment_variables 环境变量，如 REDIS_HOST、REDIS_PORT

项目仓库下的 proxy_server_config.yaml 提供了完整的示例配置文件。以下示例用于配置 Hugging Face 模型：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
model_list:
  - model_name: bce-embedding-base_v1
    litellm_params: 
      model: huggingface/maidalun1020/bce-embedding-base_v1 # 自动路由到 Hugging Face
      api_key: hf_...  # Hugging Face API 密钥
  - model_name: Meta-Llama-3-8B-Instruct
    litellm_params: 
      model: huggingface/meta-llama/Meta-Llama-3-8B-Instruct
      api_key: hf_...

general_settings: 
  master_key: sk-1234  # 调用的密钥，也是管理员登录密码
  # 如果配置 UI 界面，需数据库支持
  store_model_in_db: True 
  database_url: "postgresql://<user>:<password>@<host>:<port>/<dbname>"  # [可选] 用于代理的数据库支持

参数说明：

  • master_key 作为调用的密钥，也作为管理员的登录密码
  • store_model_in_db 保存在线的模型修改
  • database_url UI 界面的管理需要数据库支持

Docker 配置

如果希望避免手动配置 Python 环境和数据库，官方提供了 Docker 部署方式。文档：Docker 部署。

以下是个人经过调整并验证有效的 docker-compose.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
version: "3.9"
services:
  db:
    image: postgres:latest
    container_name: litellm_db
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    env_file:
      - .env
  litellm:
    build:
      context: .
      args:
        target: runtime
    image: ghcr.io/berriai/litellm:main-latest
    depends_on:
      - db
    ports:
      - "4000:4000"
    volumes:
      - ./litellm-config.yaml:/app/config.yaml
    command: [ "--config", "/app/config.yaml", "--port", "4000", "--num_workers", "8", "--detailed_debug" ]
    env_file:
      - .env

.env 文件的内容：

1
2
3
4
5
6
7
8
9
10
11
# Postgres 配置
POSTGRES_USER=
POSTGRES_PASSWORD=
POSTGRES_DB=
# LiteLLM 配置
LITELLM_MASTER_KEY="" # 主密钥，用于代理服务器
UI_USERNAME=""   # UI 界面的用户名
UI_PASSWORD=""      # UI 界面的密码
STORE_MODEL_IN_DB='True'
# 默认端口 5432，用户名密码需与上面的 POSTGRES_USER 和 POSTGRES_PASSWORD 一致
DATABASE_URL="postgresql://<user>:<password>@<host>:<port>/<dbname>"

Flask

简介

HuggingFace 的文生图接口返回的是二进制图片数据，我们可以使用 Flask 结合 Nginx 代理，将结果以链接形式返回。

下面的代码段展示了如何实现这个功能，将数据保存在 /storage/dalle3/ 目录下，并通过 CDN 链接返回。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
from flask import Flask, request, jsonify
import requests, os, io, uuid
from datetime import datetime
from PIL import Image
import json

app = Flask(__name__)
HF_TOKEN = "hf_xxx"
HF_MODEL_ID = "ehristoforu/dalle-3-xl-v2"
HUGGING_FACE_API_URL = f"https://api-inference.huggingface.co/models/{HF_MODEL_ID}"
IMAGE_SAVE_DIR = "/storage/dalle3/"
CDN_PREFIX = "https://cdn.example.com/dalle3"

def prompt_revision(prompt):
    # 自定义规则，将用户的 Prompt 进行优化，对图像进行更细致的描述
    return prompt

def generate_images(prompt):
    headers = {"Authorization" : f"Bearer {HF_TOKEN}"}
    response = requests.post(HUGGING_FACE_API_URL, headers=headers, json={"inputs": prompt})
    if response.status_code == 200:
        timestamp = datetime.now().strftime("%Y%m%d%H%M%S") # Generate timestamp string
        image_path = os.path.join(IMAGE_SAVE_DIR, f"{timestamp}_{uuid.uuid4()[:8]}.jpeg")
        image = Image.open(io.BytesIO(response.content))
        image.save(image_path, "JPEG")
        url = f"{CDN_PREFIX}/{os.path.basename(image_path)}"
        return url
    else:
        return None

@app.route('/v1/images/generations', methods=['POST'])
def image_generation():
    # Get the raw data
    raw_data = request.data
    # Decode the raw data into a string
    decoded_data = raw_data.decode('utf-8')
    data = json.loads(decoded_data)
    prompt = data.get("prompt", "")
    n = data.get("n", 1) # Number of images to generate, TODO: support multiple images
    if prompt:
        revised_prompt = prompt_revision(prompt)
        url = generate_images(revised_prompt)
        if url:
            return jsonify({
                "created": int(datetime.now().timestamp()),
                "revised_prompt": revised_prompt,
                "data": [{"url": url}],
            })
        else:
            return jsonify({"error": "Failed to generate images"}), 500
    else:
        return jsonify({"error": "No prompt provided"}), 400

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=8080)

将文件保存为 dalle3.py 并启动模型：

1
2
# pip install gunicorn
gunicorn -w 4 -b 127.0.0.1:8080 dalle3:app

接着我们可以通过 Nginx 配置返回的 CDN 链接，如下所示：

1
2
3
4
5
6
7
8
server {
    listen 443 ssl;
    server_name cdn.example.com;
    # SSL 证书配置
    location /dalle3/ {
        alias /storage/dalle3/;
    }
}

最后，通过 OpenAI 接口的方式调用：

1
2
3
4
curl https://cdn.example.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model": "dall-e-3", "prompt": "..."}'

以上，通过 Hugging Face、LiteLLM 和 Flask 来创建一个自定义接口，用于转发并处理各种模型的请求。