快速开始

Feat AI 适合已经会写 Java 服务，现在想把模型能力接进来的开发者。

编写第一个应用

你将构建一个最小的 AI 对话应用，让模型返回一段关于 Feat 框架的介绍文本。

前置要求：JDK 8+、Maven 3.0+、以下二选一：

本地 Ollama：已安装并运行，且本地拉取了可用模型
云端模型：已准备好环境变量 FEAT_AI_API_KEY

1. 添加依赖

在 pom.xml 中加入：

<dependency>
    <groupId>tech.smartboot.feat</groupId>
    <artifactId>feat-ai</artifactId>
    <version>${feat.version}</version>
</dependency>

2. 编写程序

本地 Ollama（最快验证）
云端模型

先确认本地模型可用：

ollama run qwen2.5:7b

然后创建 HelloFeatAI.java：

import tech.smartboot.feat.ai.FeatAI;
import tech.smartboot.feat.ai.chat.ChatModel;
import tech.smartboot.feat.ai.chat.ChatStreamListener;

public class HelloFeatAI {
    public static void main(String[] args) {
        ChatModel model = FeatAI.chatModel(opts -> opts
                .baseUrl("http://localhost:11434/v1")
                .model("qwen2.5:7b")
        );

        model.chatStream("用一句话介绍 Feat 框架", new ChatStreamListener() {
            @Override
            public void onStreamResponse(String content) {
                System.out.print(content);
            }
        });
    }
}

如果你已有云端 API Key，创建 HelloFeatAI.java：

import tech.smartboot.feat.ai.FeatAI;
import tech.smartboot.feat.ai.chat.ChatModel;

public class HelloFeatAI {
    public static void main(String[] args) {
        ChatModel model = FeatAI.chatModel(opts -> opts
                .model("Qwen2.5-72B-Instruct")
        );

        model.chat("用一句话介绍 Feat 框架").thenAccept(response -> {
            System.out.println(response.getContent());
        });
    }
}

3. 运行并验证

运行 HelloFeatAI.main()，控制台应该出现一段真实文本，类似：

Feat 是一个轻量级、高性能的 Java Web 服务开发框架。

只要满足以下三点，就算成功：

没有抛异常
控制台有输出
不是空字符串

两种调用方式的区别

Feat AI 提供两种与模型交互的方式，选择取决于你的场景：

方法	返回值	适用场景
`chat(...)`	`CompletableFuture<ChatResponse>`	需要完整结果后再处理，如后端任务、数据提取
`chatStream(...)`	`void`（通过 `ChatStreamListener` 回调）	需要实时消费片段，如终端输出、前端打字机效果

继续学习

完成第一个应用后，按以下顺序深入：

对话与流式学会配置模型、同步调用和流式输出。

Agent 当模型开始需要调用工具时，从这里继续。

Embedding 当你开始做检索增强、RAG 或语义搜索时，再进入这一页。

常见问题

本地 Ollama 没有输出

确认 Ollama 服务正在运行
确认本地已拉取对应模型（ollama list）
确认 baseUrl 与本机环境一致（默认端口 11434）

云端模型报错

优先检查 FEAT_AI_API_KEY 是否在当前运行环境中可见，而不是只在另一个终端窗口 export 过。