Hugging Face

本站(springdoc.cn)中的内容来源于 spring.io ，原始版权归属于 spring.io。由 springdoc.cn 进行翻译，整理。可供个人学习、研究，未经许可，不得进行任何转载、商用或与之相关的行为。商标声明：Spring 是 Pivotal Software, Inc. 在美国以及其他国家的商标。

Hugging Face 文本生成推理服务（TGI）是专为云端部署大语言模型（LLM）设计的解决方案，通过 API 提供模型访问能力。TGI 通过连续批处理、Token 流式传输和高效内存管理等特性，为文本生成任务提供优化性能。

文本生成推理服务（TGI）要求模型必须兼容其架构特定的优化方案。虽然支持许多主流大语言模型，但并非 Hugging Face Hub 上的所有模型都能通过 TGI 部署。如需部署其他类型模型，建议改用标准的 Hugging Face 推理终端。

完整且最新的支持模型及架构列表，请参阅文本生成推理服务支持模型文档。

先决条件

你需要在 Hugging Face 创建推理端点并生成 API 访问 Token。具体操作步骤详见此处文档。

Spring AI 项目定义了两个配置属性：

spring.ai.huggingface.chat.api-key：设置为从 Hugging Face 获取的 API 令牌值。
spring.ai.huggingface.chat.url：设置为在 Hugging Face 配置模型时获取的推理端点 URL。

你可以在此处（推理端点的用户界面）找到你的推理端点 URL。

你可在 application.properties 文件中设置这些配置属性：

spring.ai.huggingface.chat.api-key=<your-huggingface-api-key>
spring.ai.huggingface.chat.url=<your-inference-endpoint-url>

为增强处理敏感信息（如 API 密钥）时的安全性，可使用 Spring 表达式语言（SpEL）引用自定义环境变量：

# In application.yml
spring:
  ai:
    huggingface:
      chat:
        api-key: ${HUGGINGFACE_API_KEY}
        url: ${HUGGINGFACE_ENDPOINT_URL}

# In your environment or .env file
export HUGGINGFACE_API_KEY=<your-huggingface-api-key>
export HUGGINGFACE_ENDPOINT_URL=<your-inference-endpoint-url>

你还可以在应用程序代码中以编程方式配置这些参数：

// Retrieve API key and endpoint URL from secure sources or environment variables
String apiKey = System.getenv("HUGGINGFACE_API_KEY");
String endpointUrl = System.getenv("HUGGINGFACE_ENDPOINT_URL");

添加仓库和 BOM

Spring AI 组件已发布在 Maven 中央仓库和 Spring Snapshot 仓库。请参阅 Artifact 仓库章节将这些仓库添加到您的构建系统。

为简化依赖管理，Spring AI 提供 BOM 以确保整个项目使用统一版本的 Spring AI。请参阅依赖管理章节将 Spring AI BOM 添加到你的构建系统。

自动配置

Spring AI 自动配置和 Starter 模块的构件名称已发生重大变更。更多信息请参阅升级说明。

Spring AI 为 Hugging Face 聊天客户端提供 Spring Boot 自动配置。要启用该功能，请将以下依赖添加到项目的 Maven pom.xml 文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-huggingface</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-starter-model-huggingface'
}

请参阅依赖管理章节将 Spring AI BOM 添加到你的构建文件。

聊天属性

聊天自动配置的启用/禁用现在通过顶级属性 spring.ai.model.chat 配置：

启用：spring.ai.model.chat=huggingface（默认启用）
禁用：spring.ai.model.chat=none（或任何非 huggingface 的值）

此项变更为支持多模型配置。

前缀 spring.ai.huggingface 用于配置 Hugging Face 聊天模型实现的属性参数。

属性

说明

默认值

spring.ai.huggingface.chat.api-key

用于认证推理端点的 API Key

spring.ai.huggingface.chat.url

要连接的推理端点 URL

spring.ai.huggingface.chat.enabled（已删除，不再有效）

启用 Hugging Face 聊天模型

true

spring.ai.model.chat（已删除，不再有效）

启用 Hugging Face 聊天模型

huggingface

示例 Controller (自动配置)

创建新的 Spring Boot 项目，在 pom（或gradle）依赖中添加 spring-ai-starter-model-huggingface。

在 src/main/resources 目录下添加 application.properties 文件以启用并配置 Hugging Face 聊天模型：

spring.ai.huggingface.chat.api-key=YOUR_API_KEY
spring.ai.huggingface.chat.url=YOUR_INFERENCE_ENDPOINT_URL

将 api-key 和 url 替换为你的 Hugging Face 凭证值。

这将创建可注入类的 HuggingfaceChatModel 实现。以下是使用该聊天模型进行文本生成的简单 @Controller 类示例：

@RestController
public class ChatController {

    private final HuggingfaceChatModel chatModel;

    @Autowired
    public ChatController(HuggingfaceChatModel chatModel) {
        this.chatModel = chatModel;
    }

    @GetMapping("/ai/generate")
    public Map generate(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        return Map.of("generation", this.chatModel.call(message));
    }
}

手动配置

HuggingfaceChatModel 实现 ChatModel 接口，通过 [low-level-api] 连接 Hugging Face 推理端点。

将以下依赖添加到项目的 Maven pom.xml 文件中：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-huggingface</artifactId>
</dependency>

或添加到 Gradle build.gradle 构建文件中：

dependencies {
    implementation 'org.springframework.ai:spring-ai-huggingface'
}

请参阅依赖管理章节将 Spring AI BOM 添加到你的构建文件。

接下来，创建 HuggingfaceChatModel 并用于文本生成：

HuggingfaceChatModel chatModel = new HuggingfaceChatModel(apiKey, url);

ChatResponse response = this.chatModel.call(
    new Prompt("Generate the names of 5 famous pirates."));

System.out.println(response.getGeneration().getResult().getOutput().getContent());