Hugging Face

HuggingFace Chat

*Hugging Face Text Generation Inference (TGI) *是一种专门的部署解决方案，用于在云中服务大语言模型 (LLM), 使其可通过 API 访问。TGI 通过连续批处理、令牌流和高效的内存管理等功能，为文本生成任务提供优化的性能。

文本生成推理要求模型与其架构特定的优化兼容。虽然支持许多流行的 LLM, 但并非所有 Hugging Face Hub 上的模型都能使用 TGI 部署。如果需要部署其他类型的模型，可以考虑使用标准的 Hugging Face Inference Endpoint。

前提条件（Prerequisites）

您需要在 Hugging Face 上创建一个 Inference Endpoint, 并创建一个 API 令牌来访问该 Endpoint。更多详细信息可以在这里找到。

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

• spring.ai.huggingface.chat.api-key：将其设置为从 Hugging Face 获取的 API 令牌的值。
• spring.ai.huggingface.chat.url: 将此设置为在 Hugging Face 中预置模型时获得的推理终端 URL。

您可以在 application.properties 文件中设置以下配置属性：

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

为了提高处理 API 密钥等敏感信息时的安全性，可以使用 Spring Expression Language (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 工件发布在 Spring Milestone 和 Snapshot 存储库中。请参阅存储库部分将这些存储库添加到您的构建系统中。

为了帮助进行依赖管理，Spring AI 提供了 BOM（物料清单），以确保在整个项目中使用一致的 Spring AI 版本。请参阅依赖管理部分将 Spring AI BOM 添加到您的构建系统。

自动配置（Auto-configuration）

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'
}

聊天属性（Chat Properties）

连接属性（Connection Properties）

前缀是 spring.ai.huggingface 的属性，用于配置 Hugging Face 的链接。

示例控制器（Sample Controller）

创建一个新的 Spring Boot 项目，并将 spring-ai-starter-model-haggingface 添加到 pom (或 gradle) 依赖项中。

在 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

这将创建一个 HuggingfaceChatModel 的实现，你可以将其注入到你的类中。下面是一个简单的 @Controller 类的示例，它使用聊天模型进行文本生成。

@RestController
public class ChatController {

    private final HuggingfaceChatModel chatModel;

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


    /**
     * 文本生成
     * eg. http://localhost:8080/ai/generate?message=你好
     * @param message
     * @return
     */
    @GetMapping("/ai/generate")
    @Operation(summary = "文本生成")
    public Map<String, Object> generate(@RequestParam(value = "message", defaultValue = "你好！") String message) {
        try {
            String response = chatModel.call(message);
            return Map.of(
                    "success", true,
                    "generation", response,
                    "message", "Generated successfully"
            );
        } catch (Exception e) {
            return Map.of(
                    "success", false,
                    "error", e.getMessage(),
                    "message", "Generation failed"
            );
        }
    }

    @GetMapping("/ai/generateStream")
    public Flux<ChatResponse> generateStream(@RequestParam(value = "message", defaultValue = "Tell me a joke") String message) {
        Prompt prompt = new Prompt(new UserMessage(message));
        return this.chatModel.stream(prompt);
    }

}

手动配置（Manual Configuration）

HuggingFaceChatModel 实现 ChatModel 接口，并使用 [low-level-api] 连接到 HuggingFace 推理端点。

要启用它，添加 spring-ai-huggingface 依赖到你的项目 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'
}

接下来，创建一个 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.getResult().getOutput().getText());