|
| 1 | +/////////////////////////////////////////////////////////////////////////////// |
| 2 | + |
| 3 | + Copyright (c) 2025 Oracle and/or its affiliates. |
| 4 | + |
| 5 | + Licensed under the Apache License, Version 2.0 (the "License"); |
| 6 | + you may not use this file except in compliance with the License. |
| 7 | + You may obtain a copy of the License at |
| 8 | + |
| 9 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 10 | + |
| 11 | + Unless required by applicable law or agreed to in writing, software |
| 12 | + distributed under the License is distributed on an "AS IS" BASIS, |
| 13 | + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 14 | + See the License for the specific language governing permissions and |
| 15 | + limitations under the License. |
| 16 | + |
| 17 | +/////////////////////////////////////////////////////////////////////////////// |
| 18 | +
|
| 19 | +ifndef::rootdir[:rootdir: {docdir}/../..] |
| 20 | +
|
| 21 | +:guidesdir: {rootdir}/{flavor-lc}/guides |
| 22 | +
|
| 23 | +This guide describes how to create a sample AI powered Helidon {flavor-uc} project with LangChain4j integration. |
| 24 | +
|
| 25 | +== Introduction |
| 26 | +
|
| 27 | +include::{rootdir}/se/integrations/langchain4j/langchain4j.adoc[tag=overview] |
| 28 | +
|
| 29 | +== What you need |
| 30 | +
|
| 31 | +For this 15 minute tutorial, you will need the following: |
| 32 | +
|
| 33 | +include::{rootdir}/includes/prerequisites.adoc[tag=prerequisites] |
| 34 | +
|
| 35 | +== Generate the Project |
| 36 | +
|
| 37 | +Generate the project using the Helidon {flavor-uc} Quickstart Maven archetype. |
| 38 | +
|
| 39 | +[source,bash,subs="attributes+"] |
| 40 | +.Run the Maven archetype: |
| 41 | +---- |
| 42 | +mvn -U archetype:generate -DinteractiveMode=false \ |
| 43 | + -DarchetypeGroupId=io.helidon.archetypes \ |
| 44 | + -DarchetypeArtifactId=helidon-quickstart-{flavor-lc} \ |
| 45 | + -DarchetypeVersion={helidon-version} \ |
| 46 | + -DgroupId=io.helidon.examples \ |
| 47 | + -DartifactId=helidon-quickstart-{project-tag}-{flavor-lc} \ |
| 48 | + -Dpackage=io.helidon.examples.quickstart.{project-tag} |
| 49 | +---- |
| 50 | +
|
| 51 | +The archetype generates a Maven project in your current directory, |
| 52 | +(for example, `helidon-quickstart-{project-tag}-{flavor-lc}`). Change into this directory and build. |
| 53 | +
|
| 54 | +[source,bash,subs="attributes+"] |
| 55 | +---- |
| 56 | +cd helidon-quickstart-{project-tag}-{flavor-lc} |
| 57 | +---- |
| 58 | +
|
| 59 | +== Dependencies |
| 60 | +
|
| 61 | +Add necessary dependencies for LangChain4j integration and OpenAI provider in the project POM. |
| 62 | +
|
| 63 | +[source,xml,subs="attributes+"] |
| 64 | +---- |
| 65 | +<dependency> |
| 66 | + <groupId>io.helidon.integrations.langchain4j</groupId> |
| 67 | + <artifactId>helidon-integrations-langchain4j</artifactId> |
| 68 | +</dependency> |
| 69 | +<dependency> |
| 70 | + <groupId>io.helidon.integrations.langchain4j.providers</groupId> |
| 71 | + <artifactId>helidon-integrations-langchain4j-providers-open-ai</artifactId> |
| 72 | +</dependency> |
| 73 | +---- |
| 74 | +
|
| 75 | +You will also need extra annotation processors as LangChain4j AI services are handled as superfast build time beans. |
| 76 | +
|
| 77 | +include::{rootdir}/se/integrations/langchain4j/langchain4j.adoc[tag=annotation-processors] |
| 78 | +
|
| 79 | +== Configuration |
| 80 | +
|
| 81 | +Add to the configuration file |
| 82 | +ifdef::se-flavor[] |
| 83 | +`./src/main/resources/application.yaml` |
| 84 | +endif::se-flavor[] |
| 85 | +ifdef::mp-flavor[] |
| 86 | +`./src/main/resources/META-INF/microprofile-config.properties` |
| 87 | +endif::mp-flavor[] |
| 88 | +following LangChain4j configuration for OpenAI provider. |
| 89 | +
|
| 90 | +[TIP] |
| 91 | +Don't forget to enable your model with `enabled` set to `true` |
| 92 | +
|
| 93 | +ifdef::se-flavor[] |
| 94 | +[source,yaml] |
| 95 | +---- |
| 96 | +langchain4j: |
| 97 | + open-ai: |
| 98 | + chat-model: |
| 99 | + enabled: true |
| 100 | + model-name: "gpt-4o-mini" |
| 101 | + # Lc4j demo api key needs to be routed over lc4j proxy |
| 102 | + base-url: "http://langchain4j.dev/demo/openai/v1" |
| 103 | + api-key: "demo" |
| 104 | +---- |
| 105 | +endif::se-flavor[] |
| 106 | +ifdef::mp-flavor[] |
| 107 | +[source,properties] |
| 108 | +---- |
| 109 | +langchain4j.open-ai.chat-model.enabled=true |
| 110 | +langchain4j.open-ai.chat-model.model-name=gpt-4o-mini |
| 111 | +# Lc4j demo api key needs to be routed over lc4j proxy |
| 112 | +langchain4j.open-ai.chat-model.base-url=http://langchain4j.dev/demo/openai/v1 |
| 113 | +langchain4j.open-ai.chat-model.api-key=demo |
| 114 | +---- |
| 115 | +endif::mp-flavor[] |
| 116 | +
|
| 117 | +== Ai Service |
| 118 | +Next we need to create LangChain4j https://docs.langchain4j.dev/tutorials/ai-services[Ai service] and |
| 119 | +annotate it with `@Ai.Service` so Helidon can make a superfast build time bean from it. |
| 120 | +
|
| 121 | +[source,java,subs="none"] |
| 122 | +---- |
| 123 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=base_ai_service, indent=0] |
| 124 | +---- |
| 125 | +
|
| 126 | +ifdef::se-flavor[] |
| 127 | +
|
| 128 | +Next step is to add new Http POST handler to the webserver, you can do it by changing method `routing` in `src/main/java/io/helidon/examples/quickstart/lc4j/Main.java` like following example shows. |
| 129 | +
|
| 130 | +[source,java] |
| 131 | +---- |
| 132 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=base_resource, indent=0] |
| 133 | +---- |
| 134 | +<1> Notice how we can look up the LangChain4j Ai service as Helidon declarative superfast build time bean. |
| 135 | +
|
| 136 | +endif::se-flavor[] |
| 137 | +ifdef::mp-flavor[] |
| 138 | +Next step is to add new Http POST JAX-RS resource, create new public class `PirateResource` like following example shows. |
| 139 | +
|
| 140 | +[source,java] |
| 141 | +---- |
| 142 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=base_resource, indent=0] |
| 143 | +---- |
| 144 | +<1> Notice how we can inject the LangChain4j Ai service as Helidon declarative superfast build time bean directly in JAX-RS resource. |
| 145 | +endif::mp-flavor[] |
| 146 | +
|
| 147 | +When we build and run our Helidon AI-powered quickstart: |
| 148 | +
|
| 149 | +[source:bash] |
| 150 | +---- |
| 151 | +mvn package -DskipTests && java -jar ./target/*.jar |
| 152 | +---- |
| 153 | +
|
| 154 | +We can test our pirate service with curl: |
| 155 | +
|
| 156 | +[source:bash] |
| 157 | +---- |
| 158 | +echo "Who are you?" | curl -d @- localhost:8080/chat |
| 159 | +---- |
| 160 | +
|
| 161 | +== Prompt Template Arguments |
| 162 | +
|
| 163 | +Ofcourse all the features from LangChain4j Ai services are going to work, let's try to expand the example with |
| 164 | +https://docs.langchain4j.dev/tutorials/ai-services#usermessage[template arguments]. |
| 165 | +
|
| 166 | +[source,java,subs="none"] |
| 167 | +---- |
| 168 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=template_ai_service, indent=0] |
| 169 | +---- |
| 170 | +
|
| 171 | +Remember to fix the code calling the service. |
| 172 | +
|
| 173 | +[source,java] |
| 174 | +---- |
| 175 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=template_resource, indent=0] |
| 176 | +---- |
| 177 | +
|
| 178 | +When we build and run our Helidon AI-powered quickstart: |
| 179 | +
|
| 180 | +[source:bash] |
| 181 | +---- |
| 182 | +mvn package -DskipTests && java -jar ./target/*.jar |
| 183 | +---- |
| 184 | +
|
| 185 | +We can test our pirate service with curl: |
| 186 | +
|
| 187 | +[source:bash] |
| 188 | +---- |
| 189 | +echo "Who was your captain?" | curl -d @- localhost:8080/chat |
| 190 | +---- |
| 191 | +
|
| 192 | +== Custom Memory Provider |
| 193 | +
|
| 194 | +We can also extend the pirate example with https://docs.langchain4j.dev/tutorials/chat-memory[conversation memory]. First, we need to create a memory provider |
| 195 | +so our memory works per conversation ID. |
| 196 | +
|
| 197 | +[source,java] |
| 198 | +---- |
| 199 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=memory_provider, indent=0] |
| 200 | +---- |
| 201 | +
|
| 202 | +Now we can extend Ai service with an extra argument so we can supply identifier of our conversation with the pirate. |
| 203 | +
|
| 204 | +[source,java,subs="none"] |
| 205 | +---- |
| 206 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=memory_ai_service, indent=0] |
| 207 | +---- |
| 208 | +
|
| 209 | +We will expect conversation id as a header on the webserver. |
| 210 | +
|
| 211 | +[source,java] |
| 212 | +---- |
| 213 | +include::{sourcedir}/{flavor-lc}/guides/LangChain4jSnippets.java[tag=memory_resource, indent=0] |
| 214 | +---- |
| 215 | +
|
| 216 | +[source:bash] |
| 217 | +---- |
| 218 | +mvn package -DskipTests && java -jar ./target/*.jar |
| 219 | +---- |
| 220 | +
|
| 221 | +We can test our pirate service with curl: |
| 222 | +
|
| 223 | +[source:bash] |
| 224 | +---- |
| 225 | +echo "Hi, I am John." | curl -d @- -H "conversation-id: 123" localhost:8080/chat |
| 226 | +Ahoy there, John |
| 227 | +
|
| 228 | +echo "Do you remeber my name?" | curl -d @- -H "conversation-id: 123" localhost:8080/chat |
| 229 | +Aye, John! The name be etched in me memory like a ship’s anchor in the sand. |
| 230 | +---- |
0 commit comments