推理提供商

Hugging Face 的推理提供商（Inference Providers）使开发者能够利用世界一流的推理提供商，访问数百种机器学习模型。它们还集成在我们的客户端 SDK（适用于 JS 和 Python）中，让您可以轻松地在您偏好的提供商上探索模型的无服务器推理。

智能体快速设置

正在使用编码智能体？将其指向“推理提供商”，即可通过单个 Hugging Face Token 运行最新的可用开源模型。在下方选择您的工具，直接跳转到其设置指南。

合作伙伴

我们的平台与领先的 AI 基础设施提供商集成，让您可以通过单一、一致的 API 访问其专业功能。以下是各合作伙伴支持的功能：

为何选择“推理提供商”？

在构建 AI 应用时，管理多个提供商的 API、比较模型性能以及处理不同的可靠性问题非常困难。“推理提供商”通过以下优势解决了这些挑战：

即时访问尖端模型：超越主流提供商，访问跨多个 AI 任务的数千种专业模型。无论您需要最新的语言模型、最先进的图像生成器，还是特定领域的嵌入模型，都能在此找到。

无厂商锁定：您不再受限于单个提供商的模型目录，而是可以通过一个统一的接口访问来自 Cerebras、Groq、Together AI、Replicate 等厂商的模型。

生产级性能：为企业级工作负载而构建，具备您应用所要求的可靠性。

您可以构建以下内容：

• 文本生成：使用具备工具调用能力的大语言模型进行聊天机器人开发、内容生成和代码辅助。
• 图像和视频生成：创建自定义图像和视频，包括对 LoRA 和风格自定义的支持。
• 搜索与检索：用于语义搜索、RAG 系统和推荐引擎的最先进嵌入模型。
• 传统机器学习任务：即用型模型，适用于分类、命名实体识别 (NER)、摘要提取和语音识别。

⚡ 免费起步：“推理提供商”包含免费层级，并为 PRO 用户和企业团队组织提供额外额度。

主要功能

• 🎯 一体化 API：单个 API 即可涵盖文本生成、图像生成、文档嵌入、NER、摘要提取、图像分类等功能。
• 🔀 多提供商支持：轻松运行来自 fal、Replicate、Sambanova、Together AI 等顶级提供商的模型。
• 🚀 可扩展且可靠：专为生产环境中的高可用性和低延迟性能而构建。
• 🔧 开发者友好：简单的请求、快速的响应，以及跨 Python 和 JavaScript 客户端的一致开发体验。
• 👷 易于集成：OpenAI 聊天补全 API 的直接替代品。
• 💰 经济高效：提供商费率无额外加价。

入门

“推理提供商”可与您现有的开发工作流配合使用。无论您偏好 Python、JavaScript 还是直接 HTTP 调用，我们都提供原生 SDK 和兼容 OpenAI 的 API，助您快速上手。

我们将通过使用 openai/gpt-oss-120b（一种最先进的开放权重对话模型）的实践示例来进行演示。

推理演练场 (Inference Playground)

在深入集成之前，请使用我们的推理演练场交互式地探索模型。用您的提示词测试不同的对话补全模型，并比较响应以找到最适合您使用场景的模型。

认证

您需要一个 Hugging Face Token 来验证您的请求。请访问您的Token 设置页面，创建一个具备 Make calls to Inference Providers 权限的 fine-grained（细粒度）Token。

有关完整的 Token 管理详情，请参阅我们的安全 Token 指南。

快速上手 - 大语言模型 (LLM)

让我们从最常见的用例开始：使用大语言模型的对话式 AI。本节演示如何使用 DeepSeek V3 进行对话补全，展示了将“推理提供商”集成到应用中的不同方式。

无论您偏好我们的原生客户端、想要 OpenAI 兼容性，还是需要直接的 HTTP 访问，我们都将向您展示如何仅用几行代码即可完成部署。

Python

以下是将“推理提供商”集成到 Python 应用中的三种方式，从高级便捷性到低级控制：

pip install huggingface_hub
hf auth login # get a read token from hf.co/settings/tokens

import os
from huggingface_hub import InferenceClient

client = InferenceClient()

completion = client.chat.completions.create(
    model="openai/gpt-oss-120b",
    messages=[
        {
            "role": "user",
            "content": "How many 'G's in 'huggingface'?"
        }
    ],
)

print(completion.choices[0].message)

JavaScript

通过这些灵活的方法，将“推理提供商”集成到您的 JavaScript 应用中：

npm install @huggingface/inference

import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient(process.env.HF_TOKEN);

const chatCompletion = await client.chatCompletion({
  model: "openai/gpt-oss-120b:fastest",
  messages: [
    {
      role: "user",
      content: "How many 'G's in 'huggingface'?",
    },
  ],
});

console.log(chatCompletion.choices[0].message);

HTTP / cURL

为了进行测试、调试或集成任何 HTTP 客户端，以下是原始 REST API 格式。

默认情况下，我们的系统会自动选择指定模型的最快可用提供商（相当于 :fastest 策略——提供最高的每秒 Token 吞吐量）。

您可以通过在模型 ID 后附加策略后缀来更改提供商选择策略：使用 :cheapest 选择最具性价比的提供商（输出 Token 单价最低），或使用 :preferred 遵循您在推理提供商设置中的偏好顺序。例如：openai/gpt-oss-120b:cheapest。

您还可以通过在模型 ID 后附加提供商名称来选择您想要的提供商（例如："openai/gpt-oss-120b:sambanova"）。

curl https://router.huggingface.co/v1/chat/completions \
    -H "Authorization: Bearer $HF_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{
        "messages": [
            {
                "role": "user",
                "content": "How many G in huggingface?"
            }
        ],
        "model": "openai/gpt-oss-120b:fastest",
        "stream": false
    }'

快速上手 - 文本生成图像

让我们探索如何使用“推理提供商”根据文本提示生成图像。我们将使用 black-forest-labs/FLUX.1-dev，这是一种能生成高度详细、照片级真实图像的最先进扩散模型。

Python

使用 huggingface_hub 库实现最简单的图像生成体验，并支持自动选择提供商。

import os
from huggingface_hub import InferenceClient

client = InferenceClient(api_key=os.environ["HF_TOKEN"])

image = client.text_to_image(
    prompt="A serene lake surrounded by mountains at sunset, photorealistic style",
    model="black-forest-labs/FLUX.1-dev"
)

# Save the generated image
image.save("generated_image.png")

JavaScript

使用我们的 JavaScript SDK 实现精简的图像生成，并支持 TypeScript。

import { InferenceClient } from "@huggingface/inference";
import fs from "fs";

const client = new InferenceClient(process.env.HF_TOKEN);

const imageBlob = await client.textToImage({
  model: "black-forest-labs/FLUX.1-dev",
  inputs:
    "A serene lake surrounded by mountains at sunset, photorealistic style",
});

// Save the image
const buffer = Buffer.from(await imageBlob.arrayBuffer());
fs.writeFileSync("generated_image.png", buffer);

提供商选择

“推理提供商”API 作为一个统一的代理层，位于您的应用和多个 AI 提供商之间。理解提供商选择的工作原理对于优化应用的性能、成本和可靠性至关重要。

作为代理服务的 API

使用“推理提供商”时，您的请求会经过 Hugging Face 的代理基础设施，这带来了几个关键优势：

• 统一的身份验证与计费：对所有提供商使用单一的 Hugging Face Token。
• 自动故障转移：使用自动提供商选择 (provider="auto") 时，如果主要提供商被我们的验证系统标记为不可用，请求将自动路由到其他提供商。
• 通过客户端库提供一致的接口：使用我们的客户端库时，相同的请求格式适用于所有不同的提供商。

由于 API 充当代理，确切的 HTTP 请求在不同提供商之间可能有所不同，因为每个提供商都有各自的 API 要求和响应格式。使用我们的官方客户端库（JavaScript 或 Python）时，无论您使用 provider="auto" 还是指定特定提供商，这些特定差异都会被自动处理。

客户端侧提供商选择 (推理客户端)

使用 Hugging Face 推理客户端（JavaScript 或 Python）时，您可以显式指定提供商，也可以让系统自动选择。客户端随后会格式化 HTTP 请求，以符合所选提供商的 API 要求。

import { InferenceClient } from "@huggingface/inference";

const client = new InferenceClient(process.env.HF_TOKEN);

// Explicit provider selection
await client.chatCompletion({
  model: "deepseek-ai/DeepSeek-R1",
  provider: "sambanova", // Specific provider
  messages: [{ role: "user", content: "Hello!" }],
});

// Automatic provider selection (default: "auto")
await client.chatCompletion({
  model: "deepseek-ai/DeepSeek-R1",
  // Defaults to "auto" selection of the provider
  // provider="auto",
  messages: [{ role: "user", content: "Hello!" }],
});

提供商选择策略

• provider: "auto"（默认）：为模型选择最快的可用提供商（每秒 Token 吞吐量最高），相当于 :fastest 策略。
• provider: "specific-provider"：强制使用特定提供商（例如，“together”、“replicate”、“fal-ai”等）。

替代方案：OpenAI 兼容的聊天补全端点 (仅限聊天)

如果您更倾向于使用熟悉的 OpenAI API，或者希望以最小的变动迁移现有的聊天补全代码，我们提供了一个直接兼容的端点，它会在服务器端自动处理所有提供商的选择。

默认情况下，系统会为模型选择最快的可用提供商（每秒 Token 吞吐量最高）。这相当于在模型名称后附加 :fastest。您可以通过在模型名称后添加后缀来更改策略：

• :cheapest 选择该模型最具性价比的提供商（输出 Token 单价最低）。
• :preferred 选择您在推理提供商设置中按偏好顺序排序的首个可用提供商。

注意：此 OpenAI 兼容端点目前仅支持聊天补全任务。对于其他任务（如文本生成图像、嵌入或语音处理），请使用上述的 Hugging Face 推理客户端。

import { OpenAI } from "openai";

const client = new OpenAI({
  baseURL: "https://router.huggingface.co/v1",
  apiKey: process.env.HF_TOKEN,
});

const completion = await client.chat.completions.create({
  model: "deepseek-ai/DeepSeek-R1:fastest",
  messages: [{ role: "user", content: "Hello!" }],
});

该端点也可以通过直接 HTTP 访问，使其适用于与各种 HTTP 客户端和需要直接与聊天补全服务交互的应用集成。

curl https://router.huggingface.co/v1/chat/completions \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-R1:fastest",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

主要功能

• 服务器端提供商选择：服务器默认自动选择最快的可用提供商 (:fastest 策略)。
• 模型列表：GET /v1/models 可获取所有提供商的可用模型，包括模型在可用时的按提供商定价、上下文长度、延迟和吞吐量。
• OpenAI SDK 兼容性：可与现有的 OpenAI 客户端库兼容工作。
• 仅限聊天任务：限于对话式工作负载。

选择合适的方法

在以下情况下使用“推理客户端”：

• 您需要支持所有类型的任务（文本生成图像、语音、嵌入等）。
• 您想要对提供商的选择进行显式控制。
• 您正在构建使用多种 AI 任务的应用。

在以下情况下使用“OpenAI 兼容端点”：

• 您仅进行聊天补全任务。
• 您想要以最小的变动迁移现有的 OpenAI 代码。
• 您更倾向于服务器端的提供商管理。

在以下情况下使用“直接 HTTP”：

• 您正在实现自定义的请求逻辑。
• 您需要对请求/响应周期进行细粒度控制。
• 您正在没有可用客户端库的环境中工作。

后续步骤

现在您已经了解了基础知识，请探索以下资源以充分利用“推理提供商”：

• 发布博客文章：了解有关“推理提供商”发布的更多信息。
• 定价与计费：了解“推理提供商”的成本和计费。
• Hub 集成：了解“推理提供商”如何与 Hugging Face Hub 集成。
• 注册为提供商：加入我们的合作伙伴网络作为提供商的要求。
• Hub API：高级 API 功能和配置。
• API 参考：所有支持任务的完整参数文档。