Skip to content

Commit

Permalink
doc: Enhance readme formatting
Browse files Browse the repository at this point in the history
  • Loading branch information
@clemlesne
clemlesne committed Aug 23, 2024
1 parent c66686f commit f9e34d8
Showing 1 changed file with 174 additions and 139 deletions.
313 changes: 174 additions & 139 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ sequenceDiagram

## Deployment

Some local prerequisites are needed to deploy the solution.
### Prerequisites

[Prefer using GitHub Codespaces for a quick start.](https://codespaces.new/microsoft/call-center-ai?quickstart=1) The environment will setup automatically with all the required tools.

Expand All @@ -260,166 +260,201 @@ For other systems, make sure you have the following installed:

Then, Azure resources are needed:

1. [Create a new resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)
#### 1. [Create a new resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)

- Prefer to use lowercase and no special characters other than dashes (e.g. `ccai-customer-a`)
- Prefer to use lowercase and no special characters other than dashes (e.g. `ccai-customer-a`)

2. [Create a Communication Services resource](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource?tabs=linux&pivots=platform-azp)
#### 2. [Create a Communication Services resource](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource?tabs=linux&pivots=platform-azp)

- Same name as the resource group
- Enable system managed identity
- Same name as the resource group
- Enable system managed identity

3. [Buy a phone number](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/telephony/get-phone-number?tabs=linux&pivots=platform-azp-new)
#### 3. [Buy a phone number](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/telephony/get-phone-number?tabs=linux&pivots=platform-azp-new)

- From the Communication Services resource
- Allow inbound and outbound communication
- Enable voice (required) and SMS (optional) capabilities
- From the Communication Services resource
- Allow inbound and outbound communication
- Enable voice (required) and SMS (optional) capabilities

Now that the prerequisites are configured (local + Azure), the deployment can be done.

### Remote (on Azure)

1. Create a local `config.yaml` file
#### 1. Create the light config file

```yaml
# config.yaml
conversation:
initiate:
# Phone number the bot will transfer the call to if customer asks for a human agent
agent_phone_number: "+33612345678"
bot_company: Contoso
bot_name: Amélie
lang: {}
File is named `config.yaml`:

communication_services:
# Phone number purshased from Communication Services
phone_number: "+33612345678"
```yaml
# config.yaml
conversation:
initiate:
# Phone number the bot will transfer the call to if customer asks for a human agent
agent_phone_number: "+33612345678"
bot_company: Contoso
bot_name: Amélie
lang: {}

communication_services:
# Phone number purshased from Communication Services
phone_number: "+33612345678"

sms: {}

prompts:
llm: {}
tts: {}
```
sms: {}
#### 2. Connect to your Azure environment
prompts:
llm: {}
tts: {}
```
```zsh
az login
```

2. Connect to your Azure environment (e.g. `az login`)
3. Run deployment automation with `make deploy name=my-rg-name`
#### 3. Run deployment automation

- Wait for the deployment to finish
```zsh
make deploy name=my-rg-name
```

4. [Create a AI Search resource](https://learn.microsoft.com/en-us/azure/search/search-create-service-portal)
- Wait for the deployment to finish

- An index named `trainings`
- A semantic search configuration on the index named `default`
#### 4. [Create a AI Search resource](https://learn.microsoft.com/en-us/azure/search/search-create-service-portal)

Get the logs with `make logs name=my-rg-name`.
- An index named `trainings`
- A semantic search configuration on the index named `default`

#### 5. Get the logs

```zsh
make logs name=my-rg-name
```

### Local (on your machine)

1. Create a local `config.yaml` file

> [!TIP]
> To use a Service Principal to authenticate to Azure, you can also add the following in a `.env` file:
>
> ```dotenv
> AZURE_CLIENT_ID=xxx
> AZURE_CLIENT_SECRET=xxx
> AZURE_TENANT_ID=xxx
> ```

> [!TIP]
> If you already deployed the application to Azure and if it is working, you can:
>
> - Copy the configuration from the Azure Function App to your local machine by using the content of the `CONFIG_JSON` application setting
> - Then convert it to YAML format

```yaml
# config.yaml
resources:
public_url: https://xxx.blob.core.windows.net/public
conversation:
initiate:
agent_phone_number: "+33612345678"
bot_company: Contoso
bot_name: Robert
communication_services:
access_key: xxx
call_queue_name: call-33612345678
endpoint: https://xxx.france.communication.azure.com
phone_number: "+33612345678"
post_queue_name: post-33612345678
resource_id: xxx
sms_queue_name: sms-33612345678
cognitive_service:
# Must be of type "AI services multi-service account"
endpoint: https://xxx.cognitiveservices.azure.com
llm:
fast:
mode: azure_openai
azure_openai:
api_key: xxx
context: 16385
deployment: gpt-35-turbo-0125
endpoint: https://xxx.openai.azure.com
model: gpt-35-turbo
streaming: true
slow:
mode: azure_openai
azure_openai:
api_key: xxx
context: 128000
deployment: gpt-4o-2024-05-13
endpoint: https://xxx.openai.azure.com
model: gpt-4o
streaming: true
ai_search:
access_key: xxx
endpoint: https://xxx.search.windows.net
index: trainings
ai_translation:
access_key: xxx
endpoint: https://xxx.cognitiveservices.azure.com
```

2. Run the deployment automation with `make deploy-bicep deploy-post name=my-rg-name`

- This will deploy the Azure resources without the API server, allowing you to test the bot locally
- Wait for the deployment to finish

3. Copy local file `local.example.settings.json` to `local.settings.json` and fill the required fields

- `APPLICATIONINSIGHTS_CONNECTION_STRING`, as the connection string of the Application Insights resource
- `AzureWebJobsStorage`, as the connection string of the Azure Storage account

4. Connect to Azure Dev tunnels with `devtunnel login`, then run it with `make tunnel`

> [!IMPORTANT]
> Tunnel requires to be run in a separate terminal, because it needs to be running all the time

5. Iterate quickly with the code by running `make dev`

> [!NOTE]
> To override a specific configuration value, you can use environment variables. For example, to override the `llm.fast.endpoint` value, you can use the `LLM__FAST__ENDPOINT` variable:
>
> ```dotenv
> LLM__FAST__ENDPOINT=https://xxx.openai.azure.com
> ```

> [!NOTE]
> Also, `local.py` script is available to test the application without the need of a phone call (= without Communication Services). Run the script with:
>
> ```bash
> python3 -m tests.local
> ```

- Code is automatically reloaded on file changes, no need to restart the server
- The API server is available at `http://localhost:8080`
#### 1. Create the full config file

> [!TIP]
> To use a Service Principal to authenticate to Azure, you can also add the following in a `.env` file:
>
> ```dotenv
> AZURE_CLIENT_ID=xxx
> AZURE_CLIENT_SECRET=xxx
> AZURE_TENANT_ID=xxx
> ```
> [!TIP]
> If you already deployed the application to Azure and if it is working, you can:
>
> - Copy the configuration from the Azure Function App to your local machine by using the content of the `CONFIG_JSON` application setting
> - Then convert it to YAML format
File is named `config.yaml`:
```yaml
# config.yaml
resources:
public_url: https://xxx.blob.core.windows.net/public
conversation:
initiate:
agent_phone_number: "+33612345678"
bot_company: Contoso
bot_name: Robert
communication_services:
access_key: xxx
call_queue_name: call-33612345678
endpoint: https://xxx.france.communication.azure.com
phone_number: "+33612345678"
post_queue_name: post-33612345678
resource_id: xxx
sms_queue_name: sms-33612345678
cognitive_service:
# Must be of type "AI services multi-service account"
endpoint: https://xxx.cognitiveservices.azure.com
llm:
fast:
mode: azure_openai
azure_openai:
api_key: xxx
context: 16385
deployment: gpt-35-turbo-0125
endpoint: https://xxx.openai.azure.com
model: gpt-35-turbo
streaming: true
slow:
mode: azure_openai
azure_openai:
api_key: xxx
context: 128000
deployment: gpt-4o-2024-05-13
endpoint: https://xxx.openai.azure.com
model: gpt-4o
streaming: true
ai_search:
access_key: xxx
endpoint: https://xxx.search.windows.net
index: trainings
ai_translation:
access_key: xxx
endpoint: https://xxx.cognitiveservices.azure.com
```
#### 2. Run the deployment automation

```zsh
make deploy-bicep deploy-post name=my-rg-name
```

- This will deploy the Azure resources without the API server, allowing you to test the bot locally
- Wait for the deployment to finish

#### 3. Initialize local function config

Copy `local.example.settings.json` to `local.settings.json`, then fill the required fields:

- `APPLICATIONINSIGHTS_CONNECTION_STRING`, as the connection string of the Application Insights resource
- `AzureWebJobsStorage`, as the connection string of the Azure Storage account

#### 4. Connect to Azure Dev tunnels

> [!IMPORTANT]
> Tunnel requires to be run in a separate terminal, because it needs to be running all the time
```zsh
# Log in once
devtunnel login

# Start the tunnel
make tunnel
```

#### 5. Iterate quickly with the code

> [!NOTE]
> To override a specific configuration value, you can use environment variables. For example, to override the `llm.fast.endpoint` value, you can use the `LLM__FAST__ENDPOINT` variable:
>
> ```dotenv
> LLM__FAST__ENDPOINT=https://xxx.openai.azure.com
> ```
> [!NOTE]
> Also, `local.py` script is available to test the application without the need of a phone call (= without Communication Services). Run the script with:
>
> ```bash
> python3 -m tests.local
> ```
```zsh
make dev
```
- Code is automatically reloaded on file changes, no need to restart the server
- The API server is available at `http://localhost:8080`

## Advanced usage

Expand Down

0 comments on commit f9e34d8

Please sign in to comment.