Spring AI で質問に応答する Kotlin アプリを作成する — チュートリアル
このチュートリアルでは、Spring AI 経由で LLM に接続し、ベクターデータベースにドキュメントを保存し、それらのドキュメントのコンテキストを使用して質問に回答する Kotlin アプリを構築する方法を学びます。
このチュートリアルでは、以下のツールを使用します。
- Web アプリケーションの設定および実行のベースとしての Spring Boot
- LLM との対話およびコンテキストベースの検索を行うための Spring AI
- プロジェクトの生成およびアプリケーションロジックの実装を行うための IntelliJ IDEA
- 類似度検索用のベクターデータベースとしての Qdrant
- Qdrant をローカルで実行するための Docker
- LLM プロバイダーとしての OpenAI
開始する前に
最新バージョンの IntelliJ IDEA をダウンロードしてインストールし、Ultimate サブスクリプションを使用します。
Ultimate サブスクリプションのない IntelliJ IDEA を使用している場合や、別の IDE を使用している場合は、Web ベースのプロジェクトジェネレーター を使用して Spring Boot プロジェクトを生成できます。
OpenAI プラットフォーム で OpenAI API キーを作成し、API へのアクセス権を取得します。
Qdrant ベクターデータベースをローカルで実行するために Docker をインストールします。
Docker のインストール後、ターミナルを開き、以下のコマンドを実行してコンテナを起動します。
bashdocker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
プロジェクトの作成
代替手段として、Spring Boot の Web ベースのプロジェクトジェネレーター を使用してプロジェクトを生成することもできます。
Ultimate サブスクリプションが有効な IntelliJ IDEA で、新しい Spring Boot プロジェクトを作成します。
IntelliJ IDEA で、File | New | Project を選択します。
左側のパネルで、New Project | Spring Boot を選択します。
New Project ウィンドウで以下のフィールドとオプションを指定します。
Name: springAIDemo
Language: Kotlin
Type: Gradle - Kotlin
このオプションはビルドシステムと DSL を指定します。
Package name: org.example.springaidemo
JDK: Java JDK
このチュートリアルでは Oracle OpenJDK バージョン 21.0.1 を使用します。 JDK がインストールされていない場合は、ドロップダウンリストからダウンロードできます。
Java: 17
Java 17 がインストールされていない場合は、JDK ドロップダウンリストからダウンロードできます。

すべてのフィールドを指定したことを確認し、Next をクリックします。
Spring Boot フィールドで、最新の安定版 Spring Boot バージョンを選択します。
このチュートリアルに必要な以下の依存関係を選択します。
- Web | Spring Web
- AI | OpenAI
- SQL | Qdrant Vector Database

Create をクリックしてプロジェクトを生成し、セットアップします。
IDE が新しいプロジェクトを生成して開きます。プロジェクトの依存関係のダウンロードとインポートには少し時間がかかる場合があります。
この後、Project ビューに以下のような構造が表示されます。

生成された Gradle プロジェクトは、Maven の標準ディレクトリレイアウトに対応しています。
- アプリケーションに属するパッケージとクラスは
main/kotlinフォルダの下に配置されます。 - アプリケーションのエントリポイントは
SpringAiDemoApplication.ktファイルのmain()メソッドです。
プロジェクト設定の更新
build.gradle.ktsGradle ビルドファイルを以下のように更新します。kotlinplugins { kotlin("jvm") version "2.4.21" kotlin("plugin.spring") version "2.4.21" // Rest of the plugins }springAiVersionを2.0.0に設定します。kotlinextra["springAiVersion"] = "2.0.0"Sync Gradle Changes ボタンをクリックして Gradle ファイルを同期します。
src/main/resources/application.propertiesファイルを以下のように更新します。text# OpenAI spring.ai.openai.api-key=YOUR_OPENAI_API_KEY spring.ai.openai.chat.model=gpt-4o-mini spring.ai.openai.embedding.model=text-embedding-ada-002 # Qdrant spring.ai.vectorstore.qdrant.host=localhost spring.ai.vectorstore.qdrant.port=6334 spring.ai.vectorstore.qdrant.collection-name=kotlinDocs spring.ai.vectorstore.qdrant.initialize-schema=truespring.ai.openai.api-keyプロパティにはご自身の OpenAI API キーを設定してください。SpringAiDemoApplication.ktファイルを実行して Spring Boot アプリケーションを起動します。 起動したら、ブラウザで Qdrant コレクション ページを開いて結果を確認します。
ドキュメントの読み込みと検索を行うコントローラーの作成
ドキュメントを検索し、Qdrant コレクションに保存するための Spring @RestController を作成します。
src/main/kotlin/org/example/springaidemoディレクトリにKotlinSTDController.ktという名前の新しいファイルを作成し、以下のコードを追加します。package org.example.springaidemo {...}
kotlinpackage org.example.springaidemo // 必要な Spring およびユーティリティクラスをインポート import org.slf4j.LoggerFactory import org.springframework.ai.document.Document import org.springframework.ai.vectorstore.SearchRequest import org.springframework.ai.vectorstore.VectorStore import org.springframework.web.bind.annotation.GetMapping import org.springframework.web.bind.annotation.PostMapping import org.springframework.web.bind.annotation.RequestMapping import org.springframework.web.bind.annotation.RequestParam import org.springframework.web.bind.annotation.RestController import org.springframework.web.client.RestTemplate import kotlin.uuid.ExperimentalUuidApi import kotlin.uuid.Uuid @RestController @RequestMapping("/kotlin") class KotlinSTDController( private val restTemplate: RestTemplate, private val vectorStore: VectorStore, ) { private val logger = LoggerFactory.getLogger(this::class.java) @OptIn(ExperimentalUuidApi::class) @PostMapping("/load-docs") fun load() { // Kotlin ドキュメントからドキュメントのリストを読み込む val kotlinStdTopics = listOf( "collections-overview", "constructing-collections", "iterators", "ranges", "sequences", "collection-operations", "collection-transformations", "collection-filtering", "collection-plus-minus", "collection-grouping", "collection-parts", "collection-elements", "collection-ordering", "collection-aggregate", "collection-write", "list-operations", "set-operations", "map-operations", "read-standard-input", "opt-in-requirements", "scope-functions", "time-measurement", ) // ドキュメントのベース URL val url = "https://raw.githubusercontent.com/JetBrains/kotlin-web-site/refs/heads/master/docs/topics/" // 各ドキュメントを URL から取得してベクターストアに追加する kotlinStdTopics.forEach { topic -> val data = restTemplate.getForObject("$url$topic.md", String::class.java) data?.let { it -> val doc = Document.builder() // ランダムな UUID でドキュメントを構築する .id(Uuid.random().toString()) .text(it) .metadata("topic", topic) .build() vectorStore.add(listOf(doc)) logger.info("Document $topic loaded.") } ?: logger.warn("Failed to load document for topic: $topic") } } @GetMapping("docs") fun query( @RequestParam query: String = "operations, filtering, and transformations", @RequestParam topK: Int = 2 ): List<Document>? { val searchRequest = SearchRequest.builder() .query(query) .topK(topK) .build() val results = vectorStore.similaritySearch(searchRequest) logger.info("Found ${results?.size ?: 0} documents for query: '$query'") return results } }SpringAiDemoApplication.ktファイルを更新して、RestTemplateBean を宣言します。package org.example.springaidemo {...}
kotlinpackage org.example.springaidemo import org.springframework.boot.autoconfigure.SpringBootApplication import org.springframework.boot.runApplication import org.springframework.context.annotation.Bean import org.springframework.web.client.RestTemplate @SpringBootApplication class SpringAiDemoApplication { @Bean fun restTemplate(): RestTemplate = RestTemplate() } fun main(args: Array<String>) { runApplication<SpringAiDemoApplication>(*args) }アプリケーションを実行します。
ターミナルで
/kotlin/load-docsエンドポイントに POST リクエストを送信し、ドキュメントを読み込みます。bashcurl -X POST http://localhost:8080/kotlin/load-docsドキュメントが読み込まれたら、GET リクエストでドキュメントを検索できます。
Bashcurl -X GET http://localhost:8080/kotlin/docs
結果は Qdrant コレクション ページでも確認できます。
AI チャットエンドポイントの実装
ドキュメントが読み込まれたら、最後のステップとして、Spring AI の検索拡張生成 (RAG: Retrieval-Augmented Generation) サポートを通じて Qdrant 内のドキュメントを使用して質問に回答するエンドポイントを追加します。
KotlinSTDController.ktファイルを開き、以下のクラスをインポートします。kotlinimport org.springframework.ai.chat.client.ChatClient import org.springframework.ai.chat.client.advisor.SimpleLoggerAdvisor import org.springframework.ai.chat.client.advisor.vectorstore.QuestionAnswerAdvisor import org.springframework.ai.chat.prompt.Prompt import org.springframework.ai.chat.prompt.PromptTemplate import org.springframework.web.bind.annotation.RequestBodyChatRequestデータクラスを定義します。kotlin// チャットクエリのリクエストペイロードを表す data class ChatRequest(val query: String, val topK: Int = 3)コントローラーのコンストラクタパラメータに
ChatClient.Builderを追加します。kotlinclass KotlinSTDController( // ChatClient を作成するためのビルダーを提供 private val chatClientBuilder: ChatClient.Builder, private val restTemplate: RestTemplate, private val vectorStore: VectorStore, )コントローラークラス内に
ChatClientインスタンスを作成します。kotlin// シンプルなロギングアドバイザーでチャットクライアントを構築 private val chatClient = chatClientBuilder.defaultAdvisors(SimpleLoggerAdvisor()).build()KotlinSTDController.ktファイルの末尾に、以下のロジックを持つ新しいchatAsk()エンドポイントを追加します。kotlin@PostMapping("/chat/ask") fun chatAsk(@RequestBody request: ChatRequest): String? { // プレースホルダーを含むプロンプトテンプレートを定義 val promptTemplate = PromptTemplate( """ {query}. Please provide a concise answer based on the "Kotlin standard library" documentation. """.trimIndent() ) // プレースホルダーを実際の値に置き換えてプロンプトを作成 val prompt: Prompt = promptTemplate.create(mapOf("query" to request.query)) // 関連ドキュメントでクエリを拡張するリトリーバルアドバイザーを設定 val retrievalAdvisor = QuestionAnswerAdvisor.builder(vectorStore) .searchRequest( SearchRequest.builder() .similarityThreshold(0.7) .topK(request.topK) .build() ) .promptTemplate(promptTemplate) .build() // リトリーバルアドバイザーと共にプロンプトを LLM に送信し、生成されたコンテンツを取得 val response = chatClient.prompt(prompt) .advisors(retrievalAdvisor) .call() .content() logger.info("Chat response generated for query: '${request.query}'") return response }アプリケーションを実行します。
ターミナルで、新しいエンドポイントに POST リクエストを送信して結果を確認します。
bashcurl -X POST "http://localhost:8080/kotlin/chat/ask" \ -H "Content-Type: application/json" \ -d '{"query": "What are the performance implications of using lazy sequences in Kotlin for large datasets?", "topK": 3}'
これで完了です!OpenAI に接続し、Qdrant に保存されたドキュメントから取得したコンテキストを使用して質問に回答する Kotlin アプリが完成しました。 さまざまなクエリを試したり、他のドキュメントをインポートしたりして、さらなる可能性を探ってみてください。
完成したプロジェクトは、Spring AI デモの GitHub リポジトリ で確認できます。
次のステップ
- Kotlin AI Examples で他の Spring AI サンプルを探索する
- Spring Boot と Claude を使用してタスクマネージャーアプリケーションを作成する
