推理提供商

Hugging Face 的推理提供商为开发者提供了数百个机器学习模型的访问权限，这些模型由世界一流的推理提供商提供支持。它们还集成到我们的客户端 SDK（适用于 JS 和 Python）中，使得在您最喜欢的提供商上轻松探索模型的无服务器推理成为可能。

合作伙伴

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

为何选择推理提供商？

当您构建 AI 应用程序时，管理多个提供商 API、比较模型性能以及处理不同的可靠性是一项艰巨的任务。推理提供商通过提供以下功能来解决这些挑战：

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

零供应商锁定：与被绑定到单一提供商的模型目录不同，您可以通过一个一致的接口访问 Cerebras、Groq、Together AI、Replicate 等提供商的模型。

生产就绪性能：专为企业工作负载而构建，具有您的应用程序所需的可靠性。

以下是您可以构建的内容：

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

⚡ 免费开始：推理提供商包含一个慷慨的免费套餐，并为PRO 用户和团队与企业组织提供额外积分。

主要功能

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

入门

推理提供商与您现有的开发工作流程兼容。无论您偏好 Python、JavaScript 还是直接 HTTP 调用，我们都提供原生 SDK 和兼容 OpenAI 的 API，让您快速启动并运行。

我们将通过一个使用openai/gpt-oss-120b 的实际示例，这是一个最先进的开源权重对话模型。

推理演示场

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

认证

您需要一个 Hugging Face 令牌来验证您的请求。请访问您的令牌设置并生成一个具有Make calls to Inference Providers权限的fine-grained令牌。

有关完整的令牌管理详细信息，请参阅我们的安全令牌指南。

快速入门 - 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 格式。

默认情况下，我们的系统会自动将您的请求路由到指定模型的第一个可用提供商，遵循您在推理提供商设置中的偏好顺序。

您可以通过在模型 ID 后附加 :fastest（选择吞吐量最高的提供商）或 :cheapest（选择每个输出 token 价格最低的提供商）来更改提供商选择策略（例如，openai/gpt-oss-120b:fastest）。

您也可以通过在模型 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 令牌。
• 自动故障转移：当使用自动提供商选择（provider="auto"）时，如果主提供商被我们的验证系统标记为不可用，请求将自动路由到备用提供商。
• 通过客户端库提供一致的接口：使用我们的客户端库时，相同的请求格式适用于不同的提供商。

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

客户端提供商选择（推理客户端）

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

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"（默认）：选择模型的第一个可用提供商，按您在推理提供商设置中的偏好顺序排序。
• provider: "specific-provider"：强制使用特定提供商（例如，“together”、“replicate”、“fal-ai”等）。

替代方案：兼容 OpenAI 的聊天完成端点（仅限聊天）

如果您喜欢使用熟悉的 OpenAI API，或者希望以最少的更改迁移现有的聊天完成代码，我们提供一个即插即用的兼容端点，该端点会在服务器端自动处理所有提供商选择。

默认情况下，所选提供商是所选模型的第一个可用提供商，按您在推理提供商设置中的偏好顺序排序。您可以通过在模型名称后添加后缀来更改该策略：

• :fastest 选择模型最快的提供商（每秒 token 的吞吐量最高）
• :cheapest 选择模型最具成本效益的提供商（每个输出 token 的价格最低）

注意：此兼容 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!"
      }
    ]
  }'

主要功能

• 服务器端提供商选择：服务器自动选择最佳可用提供商
• 模型列表：GET /v1/models 返回所有提供商的可用模型
• OpenAI SDK 兼容性：与现有 OpenAI 客户端库兼容
• 仅限聊天任务：限于会话式工作负载

选择正确的方法

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

• 您需要支持所有任务类型（文本到图像、语音、嵌入等）
• 您需要对提供商选择进行明确控制
• 您正在构建使用多个 AI 任务的应用程序

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

• 您只进行聊天完成
• 您希望以最小的更改迁移现有的基于 OpenAI 的代码
• 您偏好服务器端提供商管理

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

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

后续步骤

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

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