You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Purpose
Improve the readme for better clarification on the workflow. Also adding
restrictions on the location in Bicep to prevent attempting to deploy to
a region that doesn't support OpenAI.
## Does this introduce a breaking change?
```
[ ] Yes
[x] No
```
## Pull Request Type
What kind of change does this Pull Request introduce?
```
[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[x] Documentation content changes
[ ] Other... Please describe:
```
Copy file name to clipboardExpand all lines: README.md
+64-49Lines changed: 64 additions & 49 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -21,10 +21,10 @@ We want to hear from you! Are you interested in building or currently building i
21
21
22
22
## Features
23
23
24
-
* Voice Chat, Chat and Q&A interfaces
25
-
* Explores various options to help users evaluate the trustworthiness of responses with citations, tracking of source content, etc.
26
-
* Shows possible approaches for data preparation, prompt construction, and orchestration of interaction between model (ChatGPT) and retriever (Cognitive Search)
27
-
* Settings directly in the UX to tweak the behavior and experiment with options
24
+
- Voice Chat, Chat and Q&A interfaces
25
+
- Explores various options to help users evaluate the trustworthiness of responses with citations, tracking of source content, etc.
26
+
- Shows possible approaches for data preparation, prompt construction, and orchestration of interaction between model (ChatGPT) and retriever (Cognitive Search)
27
+
- Settings directly in the UX to tweak the behavior and experiment with options
28
28
29
29
30
30
@@ -36,48 +36,57 @@ We want to hear from you! Are you interested in building or currently building i
36
36
> **Warning**<br>
37
37
> By default this sample will create an Azure App Service, Azure Static Web App, and Azure Cognitive Search resource that have a monthly cost, as well as Form Recognizer resource that has cost per document page. You can switch them to free versions of each of them if you want to avoid this cost by changing the parameters file under the infra folder (though there are some limits to consider; for example, you can have up to 1 free Cognitive Search resource per subscription, and the free Form Recognizer resource only analyzes the first 2 pages of each document.)
38
38
39
-
### Prerequisites
39
+
### Running the application
40
40
41
-
#### To Run Locally
41
+
#### GitHub Codespaces or VS Code Remote Containers
42
+
43
+
You can run this repo virtually by using GitHub Codespaces or VS Code Remote Containers. When using GitHub Codespaces or VS Code Remote Containers all the required software will be installed in the container.
44
+
45
+
Click on one of the buttons below to open this repo in one of those options.
46
+
47
+
[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=624102171&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2)
48
+
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure-samples/azure-search-openai-demo-csharp)
49
+
50
+
##### Project Initialization
51
+
52
+
1. Run `azd auth login`
53
+
1. Run `azd env new azure-search-openai-demo-csharp`
-**Important**: Ensure Docker is running before running any `azd` provisioning / deployment commands.
50
66
51
-
> **Note**<br>
52
-
> Your Azure Account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator) or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner).
53
-
54
-
#### To Run in GitHub Codespaces or VS Code Remote Containers
55
-
56
-
You can run this repo virtually by using GitHub Codespaces or VS Code Remote Containers. Click on one of the buttons below to open this repo in one of those options.
57
-
58
-
[](https://github.com/codespaces/new?hide_repo_select=true&ref=main&repo=624102171&machine=standardLinux32gb&devcontainer_path=.devcontainer%2Fdevcontainer.json&location=WestUs2)
59
-
[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/azure-samples/azure-search-openai-demo-csharp)
60
-
61
-
### Installation
62
-
63
-
#### Project Initialization
67
+
##### Project Initialization
64
68
65
69
1. Create a new folder and switch to it in the terminal
66
70
1. Run `azd auth login`
67
71
1. Run `azd init -t azure-search-openai-demo-csharp`
68
-
72
+
73
+
> **Note**<br>
74
+
> Your Azure Account must have `Microsoft.Authorization/roleAssignments/write` permissions, such as [User Access Administrator](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#user-access-administrator) or [Owner](https://learn.microsoft.com/azure/role-based-access-control/built-in-roles#owner).
75
+
76
+
### Installation
69
77
70
78
#### Starting from scratch
71
79
72
80
Execute the following command, if you don't have any pre-existing Azure services and want to start from a fresh deployment.
73
81
74
82
1. Run `azd up` - This will provision Azure resources and deploy this sample to those resources, including building the search index based on the files found in the `./data` folder.
75
-
* For the target location, the regions that currently support the model used in this sample are **East US 2** , **East US** or **South Central US**. For an up-to-date list of regions and models, check [here](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models)
83
+
- For the target location, the regions that currently support the model used in this sample are **East US 2** , **East US** or **South Central US**. For an up-to-date list of regions and models, check [here](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models)
84
+
- If you have access to multiple Azure subscriptions, you will be prompted to select the subscription you want to use. If you only have access to one subscription, it will be selected automatically.
76
85
77
86
> **Note**<br>
78
-
> This application uses the `gpt-35-turbo` model. When choosing which region to deploy to, make sure they're available in that region (i.e. EastUS). For more information, see the [Azure OpenAI Service documentation](https://learn.microsoft.com/en-us/azure/cognitive-services/openai/concepts/models#gpt-3-models-1).
87
+
> This application uses the `gpt-35-turbo` model. When choosing which region to deploy to, make sure they're available in that region (i.e. EastUS). For more information, see the [Azure OpenAI Service documentation](https://learn.microsoft.com/azure/cognitive-services/openai/concepts/models#gpt-35-models).
79
88
80
-
1. After the application has been successfully deployed you will see a URL printed to the console. Click that URL to interact with the application in your browser.
89
+
1. After the application has been successfully deployed you will see a URL printed to the console. Click that URL to interact with the application in your browser.
81
90
82
91
It will look like the following:
83
92
@@ -88,17 +97,19 @@ It will look like the following:
88
97
89
98
#### Use existing resources
90
99
100
+
If you have existing resources in Azure that you wish to use, you can configure `azd` to use those by setting the following `azd` environment variables:
101
+
91
102
1. Run `azd env set AZURE_OPENAI_SERVICE {Name of existing OpenAI service}`
92
103
1. Run `azd env set AZURE_OPENAI_RESOURCE_GROUP {Name of existing resource group that OpenAI service is provisioned to}`
93
104
1. Run `azd env set AZURE_OPENAI_CHATGPT_DEPLOYMENT {Name of existing ChatGPT deployment}`. Only needed if your ChatGPT deployment is not the default 'chat'.
94
105
1. Run `azd env set AZURE_OPENAI_GPT_DEPLOYMENT {Name of existing GPT deployment}`. Only needed if your ChatGPT deployment is not the default `davinci`.
95
106
1. Run `azd up`
96
107
97
-
> NOTE: You can also use existing Search and Storage Accounts. See `./infra/main.parameters.json` for list of environment variables to pass to `azd env set` to configure those existing resources.
108
+
> NOTE: You can also use existing Search and Storage Accounts. See `./infra/main.parameters.json` for list of environment variables to pass to `azd env set` to configure those existing resources.
98
109
99
110
#### Deploying or re-deploying a local clone of the repo
100
111
101
-
* Run `azd up`
112
+
- Run `azd up`
102
113
103
114
#### Deploying your repo using App Spaces
104
115
@@ -111,36 +122,40 @@ It will look like the following:
111
122
"resourceGroupName": {
112
123
"value": "${AZURE_RESOURCE_GROUP}"
113
124
}
125
+
```
114
126
2. Add AZURE_TAGS to main parameters file to read the value from environment variable set in GitHub Actions workflow file by App Spaces.
115
127
```json
116
128
"tags": {
117
129
"value": "${AZURE_TAGS}"
118
130
}
131
+
```
119
132
3. Add support for resource group and tags in your main bicep file to read the value being set by App Spaces.
120
133
```bicep
121
134
param resourceGroupName string = ''
122
135
param tags string = ''
123
-
4. Combine the default tags set by Azd with those being set by App Spaces. Replace *tags initialization* in your main bicep file with the following -
124
-
```bicep
136
+
```
137
+
4. Combine the default tags set by Azd with those being set by App Spaces. Replace _tags initialization_ in your main bicep file with the following -
138
+
````bicep
125
139
var baseTags = { 'azd-env-name': environmentName }
126
140
var updatedTags = union(empty(tags) ? {} : base64ToJson(tags), baseTags)
127
-
Make sure to use "updatedTags" when assigning "tags" to resource group created in your bicep file and update the other resources to use "baseTags" instead of "tags". For example -
141
+
Make sure to use "updatedTags" when assigning "tags" to resource group created in your bicep file and update the other resources to use "baseTags" instead of "tags". For example -
1. After the application deploys, set the environment variable `AZURE_KEY_VAULT_ENDPOINT`. You can find the value in the *.azure/YOUR-ENVIRONMENT-NAME/.env* file or the Azure portal.
153
+
1. After the application deploys, set the environment variable `AZURE_KEY_VAULT_ENDPOINT`. You can find the value in the _.azure/YOUR-ENVIRONMENT-NAME/.env_ file or the Azure portal.
139
154
1. Run the following .NET CLI command to start the ASP.NET Core Minimal API server (client host):
140
155
141
-
```dotnetcli
142
-
dotnet run --project ./app/backend/MinimalApi.csproj --urls=http://localhost:7181/
143
-
```
156
+
```dotnetcli
157
+
dotnet run --project ./app/backend/MinimalApi.csproj --urls=http://localhost:7181/
158
+
```
144
159
145
160
Navigate to <http://localhost:7181>, and test out the app.
146
161
@@ -150,39 +165,39 @@ Run the following if you want to give someone else access to the deployed and ex
150
165
151
166
1. Install the [Azure CLI](https://learn.microsoft.com/cli/azure/install-azure-cli)
152
167
1. Run `azd init -t azure-search-openai-demo-csharp`
153
-
1. Run `azd env refresh -e {environment name}` - Note that they will need the azd environment name, subscription Id, and location to run this command - you can find those values in your `./azure/{env name}/.env` file. This will populate their azd environment's .env file with all the settings needed to run the app locally.
154
-
1. Run `pwsh ./scripts/roles.ps1` - This will assign all of the necessary roles to the user so they can run the app locally. If they do not have the necessary permission to create roles in the subscription, then you may need to run this script for them. Just be sure to set the `AZURE_PRINCIPAL_ID` environment variable in the azd .env file or in the active shell to their Azure Id, which they can get with `az account show`.
168
+
1. Run `azd env refresh -e {environment name}` - Note that they will need the azd environment name, subscription Id, and location to run this command - you can find those values in your `./azure/{env name}/.env` file. This will populate their azd environment's .env file with all the settings needed to run the app locally.
169
+
1. Run `pwsh ./scripts/roles.ps1` - This will assign all of the necessary roles to the user so they can run the app locally. If they do not have the necessary permission to create roles in the subscription, then you may need to run this script for them. Just be sure to set the `AZURE_PRINCIPAL_ID` environment variable in the azd .env file or in the active shell to their Azure Id, which they can get with `az account show`.
155
170
156
171
#### Clean up resources
157
172
158
173
Run `azd down`
159
174
160
175
### Quickstart
161
176
162
-
* In Azure: navigate to the Azure Static Web App deployed by `azd`. The URL is printed out when `azd` completes (as "Endpoint"), or you can find it in the Azure portal.
163
-
* When running locally, navigate to <http://localhost:7181> for the client app and <http://localhost:7181/swagger> for the Open API server page.
177
+
- In Azure: navigate to the Azure Static Web App deployed by `azd`. The URL is printed out when `azd` completes (as "Endpoint"), or you can find it in the Azure portal.
178
+
- When running locally, navigate to <http://localhost:7181> for the client app and <http://localhost:7181/swagger> for the Open API server page.
164
179
165
180
Once in the web app:
166
181
167
-
* On the **Voice Chat** page, select the voice settings dialog and configure text-to-speech preferences.
168
-
* You can either type messages to interact with Blazor Clippy, or select the Speak toggle button to use speech-to-text as your input.
169
-
* Try different topics in **Chat** or **Ask Questions** context. For chat, try follow up questions, clarifications, ask to simplify or elaborate on answer, etc.
170
-
* Explore citations and sources
171
-
* Click on the "settings" icon to try different options, tweak prompts, etc.
182
+
- On the **Voice Chat** page, select the voice settings dialog and configure text-to-speech preferences.
183
+
- You can either type messages to interact with Blazor Clippy, or select the Speak toggle button to use speech-to-text as your input.
184
+
- Try different topics in **Chat** or **Ask Questions** context. For chat, try follow up questions, clarifications, ask to simplify or elaborate on answer, etc.
185
+
- Explore citations and sources
186
+
- Click on the "settings" icon to try different options, tweak prompts, etc.
172
187
173
188
## Resources
174
189
175
-
* [Revolutionize your Enterprise Data with ChatGPT: Next-gen Apps w/ Azure OpenAI and Cognitive Search](https://aka.ms/entgptsearchblog)
> The PDF documents used in this demo contain information generated using a language model (Azure OpenAI Service). The information contained in these documents is only for demonstration purposes and does not reflect the opinions or beliefs of Microsoft. Microsoft makes no representations or warranties of any kind, express or implied, about the completeness, accuracy, reliability, suitability or availability with respect to the information contained in this document. All rights reserved to Microsoft.
183
198
184
199
### FAQ
185
200
186
-
***Question***: Why do we need to break up the PDFs into chunks when Azure Cognitive Search supports searching large documents?
201
+
**_Question_**: Why do we need to break up the PDFs into chunks when Azure Cognitive Search supports searching large documents?
187
202
188
-
***Answer***: Chunking allows us to limit the amount of information we send to OpenAI due to token limits. By breaking up the content, it allows us to easily find potential chunks of text that we can inject into OpenAI. The method of chunking we use leverages a sliding window of text such that sentences that end one chunk will start the next. This allows us to reduce the chance of losing the context of the text.
203
+
**_Answer_**: Chunking allows us to limit the amount of information we send to OpenAI due to token limits. By breaking up the content, it allows us to easily find potential chunks of text that we can inject into OpenAI. The method of chunking we use leverages a sliding window of text such that sentences that end one chunk will start the next. This allows us to reduce the chance of losing the context of the text.
0 commit comments