完成第一次 Feat AI 调用

这篇指南的目标只有一个：让你在最短时间内看到模型返回的文本。不会涉及任何进阶配置，先把链路跑通。

前置条件

JDK 8+
Maven 3.0+
以下二选一：
- 本地 Ollama：已安装并运行，且本地拉取了可用模型
- 云端模型：已准备好环境变量 FEAT_AI_API_KEY

添加依赖

在 pom.xml 中加入：

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

写出第一个程序

方案一：本地 Ollama（最快验证）

先确认本地模型可用：

ollama run qwen2.5:7b

然后写一段 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：

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());
        });
    }
}

运行并确认

程序运行后，控制台应该出现一段真实文本，类似：

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

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

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

两种调用方式的区别（先记结论）

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

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

在 quickstart 阶段记住这个区别即可。具体怎么配置、怎么调优，下一篇细讲。

常见问题

本地 Ollama 没有输出

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

云端模型报错

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

程序运行完立刻退出，没看到输出

chatStream 是异步的，如果 main 方法直接结束，程序可能在回调触发前就退出了。在 quickstart 阶段可以简单加一行 Thread.sleep(30000) 观察效果，生产代码应使用更成熟的异步等待机制。

下一步

学习配置模型、多轮对话和流式回调细节：对话与流式
让模型调用外部工具：使用 Agent
文本向量化与检索增强：Embedding 与向量