Skip to content

Commit b8bd265

Browse files
JillGrant615JillGrant615
authored
Merge pull request #290635 from sonwan2020/sonwan/aca-first-ai-app
Azure Container Apps: your first AI application
2 parents ac80a63 + d42ff4c commit b8bd265

File tree

6 files changed

+292
-0
lines changed

6 files changed

+292
-0
lines changed

‎articles/container-apps/TOC.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -383,6 +383,16 @@
383383
displayName: java
384384
- name: Launch your first Java app
385385
href: java-get-started.md
386+
- name: Artificial Intelligence
387+
items:
388+
- name: PetClinic AI
389+
items:
390+
- name: Overview
391+
href: java-petclinic-ai-overview.md
392+
displayName: java
393+
- name: Deploy the PetClinic AI sample
394+
href: java-petclinic-ai-tutorial.md
395+
displayName: java
386396
displayName: java
387397
- name: Launch your first Java microservice apps with managed Java components
388398
href: java-microservice-get-started.md

‎articles/container-apps/java-petclinic-ai-overview.md

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Introduction to the Java PetClinic AI Sample in Azure Container Apps
3+
description: Explains the architecture of AI applications deployed to Azure Container Apps.
4+
author: KarlErickson
5+
ms.author: sonwan
6+
ms.service: azure-container-apps
7+
ms.topic: concept-article
8+
ms.date: 02/12/2025
9+
ms.custom: devx-track-java, devx-track-extended-java
10+
#customer intent: As a developer, I want to understand the architecture of AI applications deployed to Azure Container Apps.
11+
---
12+
13+
# Java PetClinic AI sample in Container Apps overview
14+
15+
The Spring PetClinic sample is a classic reference application that demonstrates the use of Spring Boot with Java. This tutorial features an AI-enhanced version built on Azure Container Apps that extends the traditional PetClinic management system with modern AI capabilities.
16+
17+
The application you build in this tutorial is an AI chat assistant that uses Retrieval Augmented Generation (RAG). To connect to Azure OpenAI Service, the application uses Spring AI SDKs to support the web application. For more information on RAG, see [Implement Retrieval Augmented Generation (RAG) with Azure OpenAI Service](/training/modules/use-own-data-azure-openai).
18+
19+
The application features many different services working together to introduce the AI-related features to the Spring PetClinic sample.
20+
21+
## Architecture of the AI app in Azure Container Apps
22+
23+
The following diagram shows the architecture of the AI application in Azure Container Apps:
24+
25+
:::image type="complex" source="media/java-ai-application/architecture-chart.png" alt-text="Diagram of the architecture of the AI application, which includes a Container Apps environment, an API gateway, Entra ID for authentication, and other components." lightbox="media/java-ai-application/architecture-chart.png":::
26+
Diagram that shows the architecture of the AI application. Users access the system through authentication managed by Entra ID. The Azure Container App environment contains an API gateway that enables routing for and communication with the application. The API gateway uses managed identities to securely interact with Azure Container Registry and cognitive services. The API gateway also handles communication with external users. A virtual network between the API gateway and external systems provides secure and isolated network connectivity.
27+
:::image-end:::
28+
29+
The application's API gateway, hosted in the Azure Container Apps environment, serves as the central entry point for all external requests.
30+
31+
This gateway performs the following functions:
32+
33+
- Routes and manages communication between application components.
34+
- Authenticates users through Microsoft Entra ID.
35+
- Secures access to Azure Container Registry and cognitive services using managed identities.
36+
- Handles all incoming external user requests.
37+
38+
The gateway operates within a dedicated virtual network, ensuring secure and isolated communication between the application and external systems.
39+
40+
The following table describes the key components and services featured in the application:
41+
42+
| Service or feature | Description |
43+
|-----------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
44+
| [Azure Container Apps](/azure/container-apps/overview) | A fully managed, serverless container platform for building and deploying modern apps. Handles autoscaling, traffic splitting, and revision management of containerized applications. |
45+
| [Azure Container Apps environment](/azure/container-apps/environment) | A secure boundary around a group of container apps that share networking, scaling, and management configurations. Provides the foundational runtime for a container apps deployment. |
46+
| [Azure OpenAI Service](/azure/ai-services/openai/overview) | Provides REST API access to OpenAI's ChatGPT, embeddings, and powerful language models like GPT-4. Enables AI capabilities with enterprise-grade security and compliance features. |
47+
| [Azure Container Registry](/azure/container-registry/container-registry-intro) | A private Docker registry service for storing and managing container images. Supports automated container builds, vulnerability scanning, and geo-replication. |
48+
| [Managed Identities](/entra/identity/managed-identities-azure-resources/overview) | Provides Azure services with automatically managed identities in Azure AD. Eliminates the need for credential management by allowing secure service-to-service authentication without storing credentials in code. |
49+
| [Spring AI](https://spring.io/projects/spring-ai) | Spring framework for AI engineering that applies AI design principles to the Spring ecosystem. Alternatively, [Langchain4j](https://docs.langchain4j.dev/intro) is another AI framework with its own PetClinic sample in [spring-petclinic-langchain4j](https://github.com/Azure-Samples/spring-petclinic-langchain4j). For more information, see [Chat Client API](https://docs.spring.io/spring-ai/reference/api/chatclient.html).|
50+
51+
For more information on the infrastructure as code elements of the application, see the [bicep scripts](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/infra/bicep/main.bicep) in the [Bring your first AI app in Azure Container Apps](https://github.com/Azure-Samples/spring-petclinic-ai/) repository.
52+
53+
## Code implementation
54+
55+
The following sections provide an introduction to the code to help you understand the flow of this first AI application.
56+
57+
### Making REST calls
58+
59+
The `ChatClient` controller is responsible for communicating with the chat client endpoint. The syntax for submitting a prompt in [PetclinicChatClient.java](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/src/main/java/org/springframework/samples/petclinic/genai/PetclinicChatClient.java) includes the object `chatClient` to submit user input.
60+
61+
```java
62+
return this.chatClient.prompt().user(u -> u.text(query)).call().content();
63+
```
64+
65+
### Chat customizations
66+
67+
The [`ChatConfiguration`](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/src/main/java/org/springframework/samples/petclinic/genai/ChatConfiguration.java) class customizes requests sent to `chatClient`. The following list describes some key configuration settings of `chatClient`:
68+
69+
- Connections authentication: The client connects to Azure OpenAI. Both API key authentication and managed identity authentication are supported.
70+
- Configuration settings location: For `ChatModel`, deployment `gpt-4o` and temperature `0.7` are set in the configuration file.
71+
- Vector database: The vector database stores mathematical representations of source documents, known as *embeddings*. The vector data is used by the chat API to find documents relevant to a user's question.
72+
- System prompt: Customize AI behavior and enhance performance.
73+
- API endpoints: The application features customized Azure Functions endpoints so that OpenAI can interact with the application.
74+
- Advisors: Advisors provide a flexible and powerful way to intercept, modify, and enhance AI-driven interactions in your Spring applications.
75+
76+
### Example
77+
78+
The following code example shows how the `ChatClientCustomizer` class loads configuration information:
79+
80+
```java
81+
@Bean
82+
public ChatClientCustomizer chatClientCustomizer(VectorStore vectorStore, ChatModel model) {
83+
ChatMemory chatMemory = new InMemoryChatMemory();
84+
85+
return b -> b.defaultSystem(systemResource)
86+
.defaultFunctions("listOwners", "listVets", "addPetToOwner", "addOwnerToPetclinic")
87+
.defaultAdvisors(new PromptChatMemoryAdvisor(chatMemory),
88+
new ModeledQuestionAnswerAdvisor(vectorStore, SearchRequest.defaults(), model));
89+
}
90+
```
91+
92+
### API endpoints
93+
94+
The beans defined under `java.util.Function` are functions defined in the application context. These functions are the interface between the AI models and the PetClinic application.
95+
96+
There are sample functions in [AIFunctionConfiguration.java](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/src/main/java/org/springframework/samples/petclinic/genai/AIFunctionConfiguration.java) that communicate with the PetClinic application. Keep in mind the following details about these functions:
97+
98+
- The `@Description` annotations to functions help the AI models understand the functions in a natural language.
99+
- The function body varies, depending on your business requirements.
100+
101+
### Advisors
102+
103+
Advisors are components that modify or enhance AI prompts, which act as middleware for prompt processing.
104+
105+
This application uses two different advisors:
106+
107+
- [`QuestionAnswerAdvisor`](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/src/main/java/org/springframework/samples/petclinic/genai/ModeledQuestionAnswerAdvisor.java) calls the AI models to generate a new user query that includes the results from the search vector, before finalizing the prompt.
108+
- `PromptChatMemoryAdvisor` adds chat memory into the prompt and provides a conversation history to the chat model. With this context, the AI model can remember the context of the chat and improve the chat quality.
109+
110+
For more information, see [Advisors API](https://docs.spring.io/spring-ai/reference/api/advisors.html).
111+
112+
## Next steps
113+
114+
> [!div class="nextstepaction"]
115+
> [Deploy an AI-enabled instance of Spring PetClinic on Azure Container Apps](java-petclinic-ai-overview.md)

‎articles/container-apps/java-petclinic-ai-tutorial.md

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,167 @@
1+
---
2+
title: Deploy an AI-Enabled Instance of the Spring PetClinic on Azure Container Apps
3+
description: Use the azd automation tool to deploy a sample AI application to Azure Container Apps.
4+
services: container-apps
5+
author: KarlErickson
6+
ms.author: sonwan
7+
ms.service: azure-container-apps
8+
ms.topic: tutorial
9+
ms.date: 02/12/2025
10+
ms.custom:
11+
#customer intent: As a developer, I want to see a simple example of an AI application deployed to Azure Container Apps.
12+
---
13+
14+
# Deploy an AI-enabled instance of the Spring PetClinic on Azure Container Apps
15+
16+
In this article, you learn how to use [Azure OpenAI Service](/azure/ai-services/openai/overview) and Azure Container Apps to create a natural language interface for the Spring PetClinic sample application.
17+
18+
:::image type="content" source="media/java-ai-application/home-with-chatbot.png" alt-text="Screenshot of the home page of PetClinic." lightbox="media/java-ai-application/home-with-chatbot.png":::
19+
20+
For information on the architectural details of this application, see [Java PetClinic AI sample in Container Apps overview](./java-petclinic-ai-overview.md).
21+
22+
## Considerations
23+
24+
- Deployment time: The AI-enable application deployed in this article requires a series of connected services to operate. Deployment times can take upwards of 15 minutes to complete. Plan your time accordingly as you work through this tutorial.
25+
- Model availability: The sample application uses [Azure OpenAI Service](/azure/ai-services/openai/overview) deployment modules `gpt-4o` and `text-embedding-ada-002`, which might not be available in all Azure regions.
26+
27+
For more information on availability, see [Azure OpenAI Service models](/azure/ai-services/openai/concepts/models?tabs=global-standard,standard-chat-completions) and select your desired deployment region. For best results, consider using one of the following regions: East US, East US 2, North Central US, South Central US, Sweden Central, West US, or West US 3.
28+
29+
## Prerequisites
30+
31+
- An Azure subscription. [Create one for free.](https://azure.microsoft.com/free/).
32+
- `Contributor` and `User Access Administrator` roles, or the `Owner` role. For more information, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.yml?tabs=current).
33+
- [A GitHub account](https://github.com/join).
34+
- The latest version of [git](https://git-scm.com/downloads).
35+
- The [Microsoft Build of Open JDK](/java/openjdk/install), version 17 or higher.
36+
- [Azure Developer CLI](/azure/developer/azure-developer-cli/install-azd).
37+
- [Azure CLI](/cli/azure/install-azure-cli).
38+
- [Maven](https://maven.apache.org/download.cgi).
39+
40+
## Setup
41+
42+
1. Clone the sample application to your machine by using the following command:
43+
44+
```bash
45+
git clone https://github.com/Azure-Samples/spring-petclinic-ai.git
46+
```
47+
48+
1. Navigate to the **spring-petclinic-ai** folder by using the following command:
49+
50+
```bash
51+
cd spring-petclinic-ai
52+
```
53+
54+
1. If you don't already have it, install the `containerapp` extension for the Azure CLI by using the following command:
55+
56+
```azurecli
57+
az extension add --name containerapp --upgrade
58+
```
59+
60+
1. Securely log in to your Azure account by using the following command:
61+
62+
```azurecli
63+
az auth login
64+
```
65+
66+
This command opens a web page where you can enter your Azure credentials to authenticate.
67+
68+
## Deploy
69+
70+
1. Automatically deploy the application by using the following command:
71+
72+
```azdeveloper
73+
azd up
74+
```
75+
76+
1. When you're prompted, enter **my-first-ai** for the environment name.
77+
78+
After that, enter values for `Azure Subscription` and `Azure location`, substituting your actual values for the `<..>` placeholders in the following prompts:
79+
80+
```bash
81+
? Enter a new environment name: my-first-ai
82+
? Select an Azure Subscription to use: <SUBSCRIPTION>
83+
? Select an Azure location to use: <REGION>
84+
```
85+
86+
Once you provide all the required values, you might need to wait upwards of 15 minutes for the application to deploy.
87+
88+
When deployment is complete, you see output similar to the following to notify you of a successful deployment:
89+
90+
```output
91+
(✓) Done: Resource group: rg-my-first-ai (5.977s)
92+
(✓) Done: Virtual Network: vnet-my-first-ai (7.357s)
93+
(✓) Done: Container Registry: crb36onby7z5ooc (25.742s)
94+
(✓) Done: Azure OpenAI: openai-my-first-ai (25.324s)
95+
(✓) Done: Azure AI Services Model Deployment: openai-my-first-ai/text-embedding-ada-002 (42.909s)
96+
(✓) Done: Azure AI Services Model Deployment: openai-my-first-ai/gpt-4o (44.21s)
97+
(✓) Done: Container Apps Environment: aca-env-my-first-ai (3m1.361s)
98+
(✓) Done: Container App: petclinic-ai (22.701s)
99+
100+
INFO: Deploy finish succeed!
101+
INFO: App url: petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io
102+
103+
Packaging services (azd package)
104+
105+
(✓) Done: Packaging service petclinic-ai
106+
107+
Deploying services (azd deploy)
108+
109+
(✓) Done: Deploying service petclinic-ai
110+
- Endpoint: https://petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io/
111+
112+
SUCCESS: Your up workflow to provision and deploy to Azure completed in 17 minutes 40 seconds.
113+
```
114+
115+
1. Locate the application URL.
116+
117+
Inspect the output and find the deployment success message and copy the URL to the clipboard.
118+
119+
The success message resembles the following output:
120+
121+
```output
122+
INFO: Deploy finish succeed!
123+
INFO: App url: https://petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io
124+
```
125+
126+
## Try your application
127+
128+
1. View the application in a web browser using the URL you copied at the end of the last section.
129+
130+
1. You can interact with the chatbot via prompts like the following:
131+
132+
- List all registered pet owners.
133+
- Add a new pet owner named Steve.
134+
- Change Steve's name to Steven.
135+
- Add a pet named Spot.
136+
- List all vets in your system.
137+
138+
The following image shows the result of asking the application to add a new pet owner to the system:
139+
140+
:::image type="content" source="media/java-ai-application/add-new-item.png" alt-text="Screenshot of AI chat assistant adding a new owner, complete with address and other information, and information about a pet." lightbox="media/java-ai-application/add-new-item.png":::
141+
142+
## Updates
143+
144+
As you experiment with the sample, if you want to deploy any changes to the application, you can use the following commands to publish your changes:
145+
146+
```azdeveloper
147+
azd package
148+
azd deploy
149+
```
150+
151+
## Clean up resources
152+
153+
If you plan to continue working with subsequent tutorials, you might want to retain these resources. When you no longer need the resources, delete the resource group, which also deletes its resources.
154+
155+
### [Azure portal](#tab/azure-portal)
156+
157+
To delete the resources, use the Azure portal to find the resource group of this sample, and then delete it.
158+
159+
### [Azure CLI](#tab/azure-cli)
160+
161+
To delete the resource group, use the following command:
162+
163+
```azurecli
164+
az group delete --name rg-first-ai
165+
```
166+
167+
---

‎articles/container-apps/media/java-ai-application/add-new-item.png

72.3 KB
Loading

‎articles/container-apps/media/java-ai-application/architecture-chart.png

313 KB
Loading

‎articles/container-apps/media/java-ai-application/home-with-chatbot.png

23.1 KB
Loading

0 commit comments

Comments
 (0)