Skip to content

Commit 17152ca

Browse files
craigshoemakercraigshoemaker
committed
Updated drafts
1 parent cc9309b commit 17152ca

File tree

3 files changed

+313
-6
lines changed

3 files changed

+313
-6
lines changed

‎articles/container-apps/TOC.yml

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -364,12 +364,14 @@
364364
href: java-get-started.md
365365
- name: Artificial Intelligence
366366
items:
367-
- name: Introduction to the PetClinic AI sample
368-
href: java-ai-in-container-apps-conceptual-overview.md
369-
displayName: java
370-
- name: Launch your first AI application
371-
href: first-java-ai-application.md
372-
displayName: java
367+
- name: PetClinic AI
368+
items:
369+
- name: Overview
370+
href: java-petclinic-ai-overview.md
371+
displayName: java
372+
- name: Deploy the PetClinic AI sample
373+
href: java-petclinic-ai-tutorial.md
374+
displayName: java
373375
displayName: java
374376
- name: Launch your first Java microservice apps with managed Java components
375377
href: java-microservice-get-started.md

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
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/10/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 which extends the traditional pet clinic management system with modern AI capabilities.
16+
17+
The application you build in this tutorial is 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/first-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/first-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:
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 are 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 container apps deployment. |
46+
| [Azure OpenAI Service](/azure/ai-services/openai/overview) | Provides REST API access to OpenAI's powerful language models like GPT-4, embeddings, and ChatGPT. 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 detail on infrastructure as code elements of the application, refer to the [bicep scripts](https://github.com/Azure-Samples/spring-petclinic-ai/blob/main/infra/bicep/main.bicep) in the [spring-petclinic-ai](https://github.com/Azure-Samples/spring-petclinic-ai/) repository.
52+
53+
### Code implementation
54+
55+
The following information is an introduction to the code for readers to 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 are 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+
71+
- **Configuration settings location**: For `ChatModel`, deployment `gpt-4o` and temperature `0.7` are set in the configuration file.
72+
73+
- **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.
74+
75+
- **System prompt**: Customize AI behavior and enhance performance.
76+
77+
- **API endpoints**: The application features customized Azure Functions endpoints so that OpenAI to interact with the application.
78+
79+
- **Advisors**: Advisors provide a flexible and powerful way to intercept, modify, and enhance AI-driven interactions in your Spring applications.
80+
81+
#### Example
82+
83+
The following code listing shows how the `ChatClientCustomizer` class loads configuration information.
84+
85+
```java
86+
@Bean
87+
public ChatClientCustomizer chatClientCustomizer(VectorStore vectorStore, ChatModel model) {
88+
ChatMemory chatMemory = new InMemoryChatMemory();
89+
90+
return b -> b.defaultSystem(systemResource)
91+
.defaultFunctions("listOwners", "listVets", "addPetToOwner", "addOwnerToPetclinic")
92+
.defaultAdvisors(new PromptChatMemoryAdvisor(chatMemory),
93+
new ModeledQuestionAnswerAdvisor(vectorStore, SearchRequest.defaults(), model));
94+
}
95+
```
96+
97+
### API endpoints
98+
99+
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 PetClinc application.
100+
101+
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) which communicate with the PetClinic application.
102+
103+
Keep in mind the following details about these functions:
104+
105+
- The `@Description` annotations to functions help the AI models understand the functions in a natural language.
106+
- The function body varies depending on your business requirements.
107+
108+
### Advisors
109+
110+
Advisors are components that modify or enhance AI prompts which act as middleware for prompt processing.
111+
112+
This application uses two different advisors:
113+
114+
- [`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 that generate a new user which includes results from the search vector before finalizing the prompt.
115+
116+
- `PromptChatMemoryAdvisor`adds chat memory into the prompt and provide 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.
117+
118+
For more information, see [Advisors API](https://docs.spring.io/spring-ai/reference/api/advisors.html).
119+
120+
## Next steps
121+
122+
> [!div class="nextstepaction"]
123+
> [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: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
---
2+
title: Deploy an AI-enabled instance of 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/10/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 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/first-java-ai-application/home-with-chatbot.png" alt-text="Screenshot of the home page of PetClinic." lightbox="media/first-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+
26+
- **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.
27+
28+
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.
29+
30+
## Prerequisites
31+
32+
Before you begin, ensure you have the following setup:
33+
34+
- **Azure subscription**: You can [create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) if you don't have an existing account.
35+
36+
- **Security context**: To perform this quickstart, you need the `Contributor` and `User Access Administrator` roles, or the `Owner` role.
37+
38+
For more information, see [Assign Azure roles using the Azure portal](../role-based-access-control/role-assignments-portal.yml?tabs=current).
39+
40+
- **GitHub account**: Get one for [free](https://github.com/join).
41+
42+
- **git**: Install the latest version of [git](https://git-scm.com/downloads).
43+
44+
- **Microsoft Build of Open JDK**: Install [Microsoft Build of Open JDK](/java/openjdk/install). Use version 17 at a minimum.
45+
46+
- **Azure Command-Line interface (CLI)**: Install [Azure CLI](/azure/developer/azure-developer-cli/install-azd) to manage your Azure resources via command line.
47+
48+
- **Maven**: Install the latest version of [Maven](https://maven.apache.org/download.cgi).
49+
50+
## Setup
51+
52+
1. Clone the sample application to your machine.
53+
54+
Open your terminal or command prompt to run the following command.
55+
56+
```bash
57+
git clone https://github.com/Azure-Samples/spring-petclinic-ai.git
58+
```
59+
60+
1. Change into the *spring-petclinic-ai* folder.
61+
62+
```bash
63+
cd spring-petclinic-ai
64+
```
65+
66+
1. If you don't already have it, install the Azure CLI.
67+
68+
```bash
69+
az extension add --name containerapp --upgrade
70+
```
71+
72+
1. Log in to Azure.
73+
74+
Use the `auth` command to securely log in to your Azure account using the Azure CLI.
75+
76+
```bash
77+
az auth login
78+
```
79+
80+
This command opens a web page where you can enter your Azure credentials to authenticate.
81+
82+
## Deploy
83+
84+
1. Automatically deploy the application by with the `azd up` command.
85+
86+
```azurecli
87+
azd up
88+
```
89+
90+
1. When you're prompted you for a name, enter **my-first-ai** for the environment name.
91+
92+
After that, enter values for `Azure Subscription` and `Azure location`, substituting your actual values for the `<..>` placeholders in the following prompts:
93+
94+
```bash
95+
? Enter a new environment name: my-first-ai
96+
? Select an Azure Subscription to use: <SUBSCRIPTION>
97+
? Select an Azure location to use: <REGION>
98+
```
99+
100+
Once you provide all the required values, you might need to wait upwards of 15 minutes for the application to deploy.
101+
102+
When deployment is complete, you see output similar to the following to notify you of a successful deployment.
103+
104+
```output
105+
(✓) Done: Resource group: rg-my-first-ai (5.977s)
106+
(✓) Done: Virtual Network: vnet-my-first-ai (7.357s)
107+
(✓) Done: Container Registry: crb36onby7z5ooc (25.742s)
108+
(✓) Done: Azure OpenAI: openai-my-first-ai (25.324s)
109+
(✓) Done: Azure AI Services Model Deployment: openai-my-first-ai/text-embedding-ada-002 (42.909s)
110+
(✓) Done: Azure AI Services Model Deployment: openai-my-first-ai/gpt-4o (44.21s)
111+
(✓) Done: Container Apps Environment: aca-env-my-first-ai (3m1.361s)
112+
(✓) Done: Container App: petclinic-ai (22.701s)
113+
114+
INFO: Deploy finish succeed!
115+
INFO: App url: petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io
116+
117+
Packaging services (azd package)
118+
119+
(✓) Done: Packaging service petclinic-ai
120+
121+
Deploying services (azd deploy)
122+
123+
(✓) Done: Deploying service petclinic-ai
124+
- Endpoint: https://petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io/
125+
126+
SUCCESS: Your up workflow to provision and deploy to Azure completed in 17 minutes 40 seconds.
127+
```
128+
129+
1. Locate the application URL.
130+
131+
Inspect the output and find the deployment success message and copy the URL to the clipboard.
132+
133+
The success message resembles the following output:
134+
135+
```output
136+
INFO: Deploy finish succeed!
137+
INFO: App url: https://petclinic-ai.<CLUSTER>.<REGION>.azurecontainerapps.io
138+
```
139+
140+
## Try your application
141+
142+
1. Go to the application in a web browser using the URL you copied in the last step.
143+
144+
1. You can interact with the chatbot by via prompts like:
145+
146+
- List all registered pet owners.
147+
- Add a new pet owner named Steve.
148+
- Change Steve's name to Steven.
149+
- Add a pet named Spot.
150+
- List all vets in your system.
151+
152+
The following image shows the result of asking the application to add a new pet owner to the system.
153+
154+
:::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/first-java-ai-application/add-new-item.png":::
155+
156+
## Updates
157+
158+
As you experiment with the sample, if you want to deploy any changes to the application, you can run the following commands to publish your changes.
159+
160+
```azurecli
161+
azd package
162+
azd deploy
163+
```
164+
165+
## Clean up resources
166+
167+
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.
168+
169+
### [Azure portal](#tab/azure-portal)
170+
171+
To delete the resources, use the Azure portal to find the resource group of this sample, and then delete it.
172+
173+
### [Azure CLI](#tab/azure-cli)
174+
175+
To delete the resource group, use the following command:
176+
177+
```azurecli
178+
az group delete --name rg-first-ai
179+
```
180+
181+
---
182+

0 commit comments

Comments
 (0)