完成第一次 Feat AI 调用

这篇指南不追求覆盖所有 AI 能力。它只做一件事：让模型真正返回结果。先把链路打通，再去学对话配置、Embedding 和 Agent。

你将构建什么

你将写出一个最小的 Feat AI 调用程序：

• 连接本地 Ollama，或者连接云端模型
• 发出一条提示词
• 在控制台看到模型返回的文本

你需要什么

• JDK 8 或更高版本
• Maven 3.0 或更高版本
• 二选一：
  • 本地模型：已安装并运行 Ollama
  • 云端模型：已准备好环境变量 FEAT_AI_API_KEY

添加依赖

在 pom.xml 中加入 feat-ai：

pom.xml

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

Note

feat-ai 已经传递依赖了 feat-core，通常不需要额外再引入。

选择模型来源

方案一：本地 Ollama

如果你只想最快验证链路，优先用本地 Ollama。

先确认模型已经可用，例如：

ollama run qwen2.5:7b

然后写一个最小程序：

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
                .baseUrl("http://localhost:11434/v1")
                .model("qwen2.5:7b")
        );

        model.chatStream("用一句话介绍 Feat 框架", System.out::print);
    }
}

方案二：云端模型

如果你已经拿到云端 API Key，也可以直接走云端：

HelloFeatAI.java

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

public class HelloFeatAI {
    public static void main(String[] args) {
        ChatModel model = FeatAI.chatModel(opts -> opts
                .model(ChatModelVendor.GiteeAI.Qwen2_5_72B_Instruct)
        );

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

Caution

如果你使用云端模型但没有正确设置 FEAT_AI_API_KEY，程序通常会在初始化阶段直接失败，而不是返回空内容。

运行并确认结果

程序运行成功后，你应该看到模型返回一段文本。内容不必完全固定，但至少应该满足：

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

一个典型结果可能类似：

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

chat 和 chatStream 有什么区别

这两个方法看起来很像，但使用场景不同：

• chat(...)：等整段回复生成完成后再给你
• chatStream(...)：一边生成一边回调，适合终端输出和前端流式展示

在 quickstart 阶段，能记住这个区别就够了。参数调优、多轮对话和系统提示词放到下一篇再学。

接下来读什么

如果第一次调用已经成功，接下来通常会沿着这条路径继续：

• 想学同步调用、流式输出和多轮对话：看 对话与流式
• 想让模型调用工具：看 使用 Agent
• 想做检索增强：看 Embedding 与向量

常见问题

本地 Ollama 一直没有输出

优先检查：

1. Ollama 服务是否在运行
2. 本地是否真的有对应模型
3. baseUrl 是否与本机环境一致

云端模型直接报错

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

我想直接做 Agent，不想再学一轮对话

不建议。
先把最基本的模型调用理解清楚，再去做 Agent，排错成本会低很多。