AI-102: Implement Natural Language Processing Solutions

Target Exam: AI-102 – Azure AI Engineer

Table of Contents

1. Course Overview
2. Module 1 — Analyze and Translate Text
   • 2.1 Azure Language in Foundry Tools — Introduction
   • 2.2 Key Phrase and Entity Extraction
   • 2.3 Sentiment Analysis
   • 2.4 Personally Identifiable Information Detection (PII)
   • 2.5 Language Detection
   • 2.6 Text and Document Translation (Azure AI Translator)
3. Module 2 — Process and Translate Speech
   • 3.1 Azure Speech in Foundry Tools — Introduction
   • 3.2 Text-to-Speech with Generative Neural Voices
   • 3.3 SSML — Speech Synthesis Markup Language
   • 3.4 Speech-to-Text
   • 3.5 Custom Speech
   • 3.6 Keyword and Intent Recognition
   • 3.7 Speech Translation
4. Module 3 — Custom Language Models
   • 4.1 Conversational Language Understanding (CLU)
   • 4.2 Train, Evaluate and Deploy a CLU Model
   • 4.3 Optimize, Back Up and Recover a CLU Model
   • 4.4 Consuming a CLU Model from a Client Application
   • 4.5 Custom Question Answering
   • 4.6 Multi-turn Conversation
   • 4.7 Alternate Phrasing and Chit-chat
   • 4.8 Knowledge Base Export / Import
   • 4.9 Multilingual Question Answering Solution
   • 4.10 Custom Translator
5. References and Resources

1. Course Overview

AI-102 exam objective: implementation of NLP (Natural Language Processing) solutions

Global Architecture of Azure AI NLP Services

┌──────────────────────────────────────────────────────────┐
│               Microsoft AI Foundry (portal)              │
│  ┌────────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │ Azure Language │  │ Azure Speech │  │  Azure       │ │
│  │ in Foundry     │  │ in Foundry   │  │  Translator  │ │
│  │ Tools          │  │ Tools        │  │  in Foundry  │ │
│  └────────┬───────┘  └──────┬───────┘  └──────┬───────┘ │
└───────────┼─────────────────┼─────────────────┼─────────┘
            │                 │                 │
     REST API / SDK    REST API / SDK    REST API / SDK
            │                 │                 │
    ┌───────▼───────┐  ┌───────▼───────┐  ┌────▼──────────┐
    │  Applications │  │  Applications │  │  Applications │
    │  .NET / Java  │  │  .NET / Java  │  │  .NET / Java  │
    │  JS / Python  │  │  JS / Python  │  │  JS / Python  │
    └───────────────┘  └───────────────┘  └───────────────┘

2. Module 1 — Analyze and Translate Text

2.1 Azure Language in Foundry Tools — Introduction

Formerly Azure AI Language (formerly Azure Cognitive Services).
Azure Language uses AI to understand and analyze text.

Available APIs

Service Access Options

flowchart LR
    A[Developer] --> B[Microsoft Foundry Playground / Language Studio]
    A --> C[Direct REST API]
    A --> D[SDK: .NET / Java / JS / Python]
    B --> E[Azure Language Service]
    C --> E
    D --> E

Provisioning with Azure CLI

az cognitiveservices account create \
  --name ai102-language \
  --resource-group AI102-RG \
  --location eastus \
  --kind TextAnalytics \
  --sku S \
  --yes

2.2 Key Phrase and Entity Extraction

Concepts

Real-world scenario: Globomantics receives thousands of customer emails. Azure Language extracts key phrases (e.g., “service outage”, “billing issue”) to automatically create support tickets.

Best Practices

• Clean the text (remove HTML tags, typos)
• Combine Key Phrase Extraction + Entity Recognition for richer context
• Use Azure AI Search to index and enrich results
• Visualize key phrases with Power BI

REST API Call — Key Phrase Extraction

POST https://{endpoint}/language/:analyze-text?api-version=2022-05-01
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-key}

{
  "kind": "KeyPhraseExtraction",
  "parameters": {
    "modelVersion": "latest"
  },
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "Dr. Smith has a very modern medical office, and she has great staff."
      }
    ]
  }
}

Response:

{
  "results": {
    "documents": [
      {
        "id": "1",
        "keyPhrases": [
          "modern medical office",
          "Dr. Smith",
          "great staff"
        ]
      }
    ]
  }
}

2.3 Sentiment Analysis

Concepts

Sentiment analysis classifies text as positive, negative, or mixed, with a confidence score (0 to 1).

Use cases:

• Measuring customer satisfaction
• Analyzing online product reviews
• Monitoring brand perception

REST API Call — Sentiment Analysis

POST https://{endpoint}/language/:analyze-text?api-version=2022-05-01
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-key}

{
  "kind": "SentimentAnalysis",
  "analysisInput": {
    "documents": [
      {
        "id": "1",
        "language": "en",
        "text": "The food and service were unacceptable. The concierge was nice, however."
      },
      {
        "id": "2",
        "language": "en",
        "text": "I am really enjoying this AI-102 training!"
      }
    ]
  }
}

Response (excerpt):

{
  "documents": [
    { "id": "1", "sentiment": "negative", "confidenceScores": { "positive": 0.0, "negative": 1.0 } },
    { "id": "2", "sentiment": "positive", "confidenceScores": { "positive": 0.98, "negative": 0.01 } }
  ]
}

Sentiment Results — Visualization

Negative text  : ████████████████████░░░░░░ negative=1.00
Positive text  : ████████████████████████▓░ positive=0.98
Mixed text     : ████████████░░░░░░░░░░░░░░ positive=0.49 / negative=0.50

2.4 Personally Identifiable Information Detection (PII)

What Is PII?

Personally Identifiable Information (PII) refers to any data that can identify a person:

Why Detect PII?

• Compliance with regulations (GDPR, HIPAA)
• Protecting customer privacy
• Filter personal data before sending to AI applications

Azure Language PII Detection Methods

flowchart LR
    A[Input text] --> B{Azure Language PII Detection}
    B --> C[Machine Learning Models]
    B --> D[Pattern-based Matching]
    C --> E[Result: detected PII entities]
    D --> E

Workflow in Microsoft Foundry Playground

1. Navigate to Playgrounds → Language Playground → Extract PII from text
2. Choose the API version (avoid preview versions in production)
3. Paste the text to analyze
4. Click Run
5. Check the JSON tab to see the raw API response
6. Click View code to get C#, Java, JavaScript, or Python code

2.5 Language Detection

API Response

REST API Call — Language Detection

POST https://{endpoint}/language/:analyze-text?api-version=2022-05-01
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-key}

{
  "kind": "LanguageDetection",
  "analysisInput": {
    "documents": [
      { "id": "1", "text": "今日は良い天気ですね。" }
    ]
  }
}

Response:

{
  "documents": [
    {
      "id": "1",
      "detectedLanguage": {
        "name": "Japanese",
        "iso6391Name": "ja",
        "confidenceScore": 1.0
      }
    }
  ]
}

C# SDK Example — Language Detection

using Azure;
using Azure.AI.TextAnalytics;
using Microsoft.Extensions.Configuration;

var configuration = new ConfigurationBuilder()
    .SetBasePath(Directory.GetCurrentDirectory())
    .AddJsonFile("appsettings.json", optional: false, reloadOnChange: true)
    .Build();

var endpoint = configuration["AzureAI:Language:Endpoint"];
var key = configuration["AzureAI:Language:Key"];

var client = new TextAnalyticsClient(new Uri(endpoint), new AzureKeyCredential(key));

// Detect the language of a text
var response = await client.DetectLanguageAsync(inputText);
var detected = response.Value;

Console.WriteLine($"Detected language : {detected.Name}");
Console.WriteLine($"ISO 639-1 code    : {detected.Iso6391Name}");
Console.WriteLine($"Confidence        : {detected.ConfidenceScore:0.000}");

⚠️ Important: Never store API keys in source code.
Use Azure Key Vault to store secrets in production.

2.6 Text and Document Translation (Azure AI Translator)

Formerly Azure AI Translator, now Azure Translator in Foundry Tools.

Capabilities

Supported document formats: PDF, Word, TXT, HTML

Use Cases

• Translating international customer messages and support tickets
• Translating customer-facing content (manuals, guides)
• Internal multilingual communication

REST API Call — Text Translation

curl -X POST "https://api.cognitive.microsofttranslator.com/translate?api-version=3.0&from=en&to=es-ES" \
  -H "Ocp-Apim-Subscription-Key: {your-key}" \
  -H "Ocp-Apim-Subscription-Region: eastus" \
  -H "Content-Type: application/json; charset=UTF-8" \
  -d "[{'Text':'Hello, what is your name?'}]"

⚠️ The Ocp-Apim-Subscription-Region parameter is required, otherwise the API returns 401 Unauthorized.

Response:

[
  {
    "translations": [
      { "text": "Hola, ¿cómo te llamas?", "to": "es" }
    ]
  }
]

Document Translation Architecture

┌─────────────┐     Word/PDF Document     ┌─────────────────────┐
│  Source     │ ─────────────────────────▶│  Azure Translator   │
│  Document   │                           │  in Foundry Tools   │
└─────────────┘                           └─────────┬───────────┘
                                                    │
                                          Translated + formatting
                                          preserved (bold, italic,
                                          font size)
                                                    │
                                          ┌─────────▼───────────┐
                                          │  Translated Document│
                                          └─────────────────────┘

3. Module 2 — Process and Translate Speech

3.1 Azure Speech in Foundry Tools — Introduction

Formerly Azure AI Speech.
Provides AI-powered speech services, including text-to-speech and speech-to-text.

Key Features

Access Options

flowchart LR
    A[Developer] --> B[Microsoft AI Foundry / Speech Studio]
    A --> C[REST API]
    A --> D[Speech SDK: .NET / JS / Python]
    B --> E[Azure Speech in Foundry]
    C --> E
    D --> E

Note: Microsoft is gradually retiring Speech Studio in favor of Microsoft AI Foundry.

3.2 Text-to-Speech with Generative Neural Voices

Neural Voice Characteristics

• Generated by deep learning models
• Natural-sounding with accents, intonations, and emotions
• Controlled via SSML (XML)
• Over 100 languages and dialects supported
• Customization with Custom Neural Voice

Postman Example — REST API Text-to-Speech Call

POST https://eastus.tts.speech.microsoft.com/cognitiveservices/v1
Ocp-Apim-Subscription-Key: {your-key}
Content-Type: application/ssml+xml
X-Microsoft-OutputFormat: audio-24khz-160kbitrate-mono-mp3

<speak version='1.0' xml:lang='en-US'>
  <voice xml:lang='en-US' xml:gender='Female' name='en-US-Ava:DragonHDLatestNeural'>
    This voice is generated using Azure AI Speech API!
  </voice>
</speak>

Retrieve the List of Available Voices

GET https://eastus.tts.speech.microsoft.com/cognitiveservices/voices/list
Ocp-Apim-Subscription-Key: {your-key}

C# SDK Example — Text-to-Speech

using Microsoft.CognitiveServices.Speech;

// TODO: Store secrets in Azure Key Vault, never in code.
string speechKey = "{your-key}";
string endpoint  = "https://eastus.api.cognitive.microsoft.com/";

var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), speechKey);
speechConfig.SpeechSynthesisVoiceName = "en-US-Ava:DragonHDLatestNeural";

using var speechSynthesizer = new SpeechSynthesizer(speechConfig);

Console.WriteLine("Enter text to speak >");
string? text = Console.ReadLine();

var result = await speechSynthesizer.SpeakTextAsync(text);

if (result.Reason == ResultReason.SynthesizingAudioCompleted)
    Console.WriteLine($"Speech synthesized for: [{text}]");

3.3 SSML — Speech Synthesis Markup Language

SSML is an XML markup language that lets you precisely control voice generation.

Main SSML Tags

Example 1 — Two Voices in the Same Audio File

<speak version='1.0' xml:lang='en-US'>
  <voice xml:lang='en-US' xml:gender='Female' name='en-US-Ava:DragonHDLatestNeural'>
    This voice is generated using Azure AI Speech API!
  </voice>
  <voice name="en-US-Andrew:DragonHDLatestNeural">
    This sounds good Ava!
  </voice>
</speak>

Example 2 — Emotional Style sad

<speak version='1.0'
  xmlns="http://www.w3.org/2001/10/synthesis"
  xmlns:mstts="https://www.w3.org/2001/mstts"
  xml:lang='en-US'>
  <voice xml:lang='en-US' xml:gender='Female' name='en-US-AvaNeural'>
    <mstts:express-as style="sad" styledegree="2">
      Today is a bit gloomy!
    </mstts:express-as>
  </voice>
</speak>

Example 3 — Emotional Style fearful

<speak version='1.0'
  xmlns="http://www.w3.org/2001/10/synthesis"
  xmlns:mstts="https://www.w3.org/2001/mstts"
  xml:lang='en-US'>
  <voice xml:lang='en-US' xml:gender='Female' name='en-US-AvaNeural'>
    <mstts:express-as style="fearful" styledegree="2">
      We are expecting a strong storm in the next few hours!
    </mstts:express-as>
  </voice>
</speak>

Example 4 — <emphasis> + <break>

<speak version='1.0'
  xmlns="http://www.w3.org/2001/10/synthesis"
  xmlns:mstts="https://www.w3.org/2001/mstts"
  xml:lang='en-US'>
  <voice name="en-US-AndrewMultilingualNeural">
    Today is a <emphasis level="strong">sunny day</emphasis>,
    <break/> with some wind!
  </voice>
</speak>

Example 5 — <prosody> to Adjust Rate (+40%)

<speak version='1.0'
  xmlns="http://www.w3.org/2001/10/synthesis"
  xmlns:mstts="https://www.w3.org/2001/mstts"
  xml:lang='en-US'>
  <voice name="en-US-AndrewMultilingualNeural">
    <prosody rate="+40.00%">
      Today is a <emphasis level="strong">sunny day</emphasis>,
      <break/> with some wind!
    </prosody>
  </voice>
</speak>

C# SDK Example — SSML Synthesis with <say-as>

using Microsoft.CognitiveServices.Speech;

string speechKey = "{your-key}";
string endpoint  = "https://eastus.api.cognitive.microsoft.com/";

var speechConfig = SpeechConfig.FromEndpoint(new Uri(endpoint), speechKey);

using var speechSynthesizer = new SpeechSynthesizer(speechConfig);

Console.WriteLine("Press a key to start synthesis...");
Console.ReadLine();

// Build the SSML string in code
string ssml = "<speak version=\"1.0\"";
ssml += " xmlns=\"http://www.w3.org/2001/10/synthesis\"";
ssml += " xml:lang=\"en-US\">";
ssml += " <voice name=\"en-US-AndrewMultilingualNeural\">";
ssml += " Microsoft released Windows 11 on <say-as type=\"date:mdy\"> 10/5/2021 </say-as>!";
ssml += "</voice>";
ssml += "</speak>";

var result = await speechSynthesizer.SpeakSsmlAsync(ssml);

💡 Tip: Prefer reading external SSML files rather than building XML in code, to avoid character escaping issues.

3.4 Speech-to-Text

Transcription Types

Features

• Automatic transcription with punctuation and capitalization
• Confidence score for each recognized word
• Supports multiple languages and dialects

REST API Call — Fast Transcription

POST https://eastus.api.cognitive.microsoft.com/speechtotext/transcriptions:transcribe?api-version=2024-05-15-preview
Ocp-Apim-Subscription-Key: {your-key}
Content-Type: multipart/form-data

-- form-data --
audio: [.wav file as binary]

Response (excerpt):

{
  "combinedPhrases": [
    { "text": "This voice is generated using Azure AI Speech API." }
  ],
  "phrases": [
    {
      "text": "This voice is generated using Azure AI Speech API.",
      "confidence": 0.85
    }
  ]
}

3.5 Custom Speech

When to Use Custom Speech?

Custom Speech Model Training Process

flowchart TD
    A[Prepare training data] --> B[Upload WAV files + transcriptions]
    A --> C[Upload structured Markdown text]
    B --> D[Create a Fine-tune Speech project in Foundry]
    C --> D
    D --> E[Choose a base model]
    E --> F[Train the model]
    F --> G{Evaluate performance}
    G -->|Performance acceptable| H[Deploy the model]
    G -->|Performance insufficient| A
    H --> I[REST API / SDK call]

Training Data Format

• Audio files: .wav format
• Transcriptions: text file listing each file with its content
• Structured text: Markdown file with business vocabulary

Best Practices

• Use high-quality, representative data
• Use business vocabulary lists
• Continuously refine models with new examples
• Ensure recordings are ethically sourced and consented

3.6 Keyword and Intent Recognition

Keyword Recognition vs Intent Recognition

┌──────────────────────────────────────────────────────────────┐
│                    Voice Assistant Pipeline                  │
│                                                              │
│  ┌────────────┐    ┌──────────────────┐    ┌─────────────┐  │
│  │ Microphone │───▶│ Keyword Recog.   │───▶│ Intent Recog│  │
│  │            │    │ "Hey Computer!"  │    │ "Book flight"│  │
│  └────────────┘    └──────────────────┘    └──────┬──────┘  │
│                           │                       │          │
│                    System wake-up           Business action  │
│                    (.table model)          (CLU / OpenAI)    │
└──────────────────────────────────────────────────────────────┘

⚠️ Important: The Intent Recognition service under Azure Speech was retired in September 2025.
Use Azure Language CLU or Azure OpenAI for intent recognition instead.

.table Model File

• Generated in Microsoft Foundry or Speech Studio
• Works locally without an internet connection
• Approximate size: ~4 MB

C# SDK Example — Keyword Recognition

using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Audio;

// Path to the downloaded .table model file
private const string KeywordModelPath =
    @"C:\models\custom-keyword.table";

public static async Task Main()
{
    if (!File.Exists(KeywordModelPath))
    {
        Console.Error.WriteLine($"Model not found: {KeywordModelPath}");
        return;
    }

    using var cts = new CancellationTokenSource();
    Console.CancelKeyPress += (_, e) => { e.Cancel = true; cts.Cancel(); };

    var keywordModel    = KeywordRecognitionModel.FromFile(KeywordModelPath);
    using var audioConfig      = AudioConfig.FromDefaultMicrophoneInput();
    using var keywordRecognizer = new KeywordRecognizer(audioConfig);

    Console.WriteLine("Listening for keyword... (Ctrl+C to stop)");

    while (!cts.IsCancellationRequested)
    {
        var result = await keywordRecognizer.RecognizeOnceAsync(keywordModel);
        if (result.Reason == ResultReason.RecognizedKeyword)
            Console.WriteLine("✅ Hello! How can I help you?");
    }
}

3.7 Speech Translation

Speech-to-Text Translation vs Speech-to-Speech Translation

Speech-to-Text Translation:
  [Source audio EN] → [Text EN] → [Text ES]

Speech-to-Speech Translation:
  [Source audio EN] → [Text EN] → [Text ES] → [Audio ES]

Characteristics

• Automatic source language detection
• Multiple target languages simultaneously for the same input
• Real-time streaming mode
• Batch translation mode
• Custom neural voice output support
• Simultaneous translated text + translated audio output

Use Cases

• International real-time customer support
• Multilingual educational applications
• Accessibility for international users
• Global communication (similar to the United Nations)

C# SDK Example — Speech Translation (EN → IT)

using Microsoft.CognitiveServices.Speech;
using Microsoft.CognitiveServices.Speech.Translation;

// TODO: Store in Azure Key Vault for production.
static string speechKey = "{your-key}";
static string endpoint  = "https://eastus.api.cognitive.microsoft.com/";

async static Task Main(string[] args)
{
    var speechTranslationConfig =
        SpeechTranslationConfig.FromEndpoint(new Uri(endpoint), speechKey);

    // Source language: English
    speechTranslationConfig.SpeechRecognitionLanguage = "en-US";
    // Target language: Italian
    speechTranslationConfig.AddTargetLanguage("it");

    using var audioConfig = AudioConfig.FromDefaultMicrophoneInput();
    using var translationRecognizer =
        new TranslationRecognizer(speechTranslationConfig, audioConfig);

    Console.WriteLine("Speak into the microphone...");
    var result = await translationRecognizer.RecognizeOnceAsync();

    if (result.Reason == ResultReason.TranslatedSpeech)
    {
        Console.WriteLine($"RECOGNIZED: {result.Text}");
        foreach (var element in result.Translations)
            Console.WriteLine($"TRANSLATED to '{element.Key}': {element.Value}");
    }
}

4. Module 3 — Custom Language Models

4.1 Conversational Language Understanding (CLU)

CLU Building Blocks

flowchart LR
    U[User] -->|Voice / text input| App[Application]
    App -->|Text| CLU[Azure Language CLU]
    CLU -->|Intent + Entities JSON| App
    App -->|Business action| System[Backend system]

    subgraph CLU Model
        I[Intents - Goals]
        E[Entities - Data]
        Ut[Utterances - Training examples]
    end

Best Practices for Utterances

• Aim for 10 to 15 utterances per intent to start
• Include formal and informal phrasing
• Avoid overlapping intents
• Use varied vocabulary and phrasing
• Update utterances as new user data arrives

4.2 Train, Evaluate and Deploy a CLU Model

CLU Model Lifecycle

flowchart TD
    A["Define Schema\nIntents + Entities"] --> B["Add Utterances\ntraining + test"]
    B --> C[Train the model]
    C --> D["Evaluate metrics\nF1 / Precision / Recall"]
    D -->|Not satisfactory| B
    D -->|Satisfactory| E[Deploy the model]
    E --> F[HTTP REST API endpoint]
    F --> G[Production testing]
    G -->|Continuous improvement| B

Evaluation Metrics

🎯 The F1 Score is the primary metric for evaluating your CLU model.

Training Modes

Default Data Split

80% → Training data
20% → Test data

4.3 Optimize, Back Up and Recover a CLU Model

Maintenance Tasks

flowchart LR
    A["Continuous evaluation\nF1 Score"] --> B{Performance\nacceptable?}
    B -->|No| C["Identify weak\nintents and entities"]
    C --> D["Add / modify\nutterances"]
    D --> E[Retrain the model]
    E --> A
    B -->|Yes| F["Back up model\nJSON / ZIP"]
    F --> G["Azure Blob Storage\nGitHub / Azure DevOps"]

Backup/Restore Commands via REST API (curl)

# 1. Launch the export (backup) task
curl -X POST \
  "https://{endpoint}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/:export?stringIndexType=Utf16CodeUnit&api-version=2023-04-01" \
  -H "Ocp-Apim-Subscription-Key: {your-key}" \
  -H "Content-Type: application/json"

# 2. Check the export status
GET {ENDPOINT}/language/authoring/analyze-conversations/projects/{PROJECT-NAME}/export/jobs/{JOB-ID}?api-version={API-VERSION}

# 3. Restore (import) into a new project
curl -X POST \
  "{SECONDARY-ENDPOINT}/language/authoring/analyze-conversations/projects/{NEW-PROJECT-NAME}/:import?api-version={API-VERSION}" \
  -H "Ocp-Apim-Subscription-Key: {SECONDARY-RESOURCE-KEY}" \
  -H "Content-Type: application/json" \
  -d "{'projectFileVersion': '...version...', 'storageInputUri': '...URI...'}"

Best Practices

• Back up before any major modification or retraining
• Use clear naming conventions for backup files
• Use version control (Git) to track utterance changes
• Protect files with RBAC (Role-Based Access Control)

4.4 Consuming a CLU Model from a Client Application

Consumption Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    Client Application                           │
│                                                                 │
│  1. User types or says a command                                │
│     "Please book me an economy flight with Delta"               │
│                         │                                       │
│  2. App calls the CLU endpoint via HTTP POST                    │
│                         │                                       │
│  3. The CLU model returns:                                      │
│     {                                                           │
│       "topIntent": "BookFlight",     // confidence: 90%         │
│       "entities": [                                             │
│         { "category": "Class",    "text": "economy" },         │
│         { "category": "Airline",  "text": "Delta"   }          │
│       ]                                                         │
│     }                                                           │
│                         │                                       │
│  4. App executes business logic: reservation API call           │
└─────────────────────────────────────────────────────────────────┘

C# SDK Example — CLU Model Consumption (direct REST)

using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

Console.Write("Enter your query: ");
string userInput = Console.ReadLine() ?? string.Empty;

string endpoint        = "https://{foundry-endpoint}/language/:analyze-conversations?api-version=2024-11-01";
string subscriptionKey = "{your-key}";
string projectName     = "flight-booking-clu";
string deploymentName  = "flight-booking-endpoint";

var requestBody = new
{
    kind = "Conversation",
    analysisInput = new
    {
        conversationItem = new
        {
            id            = "user1",
            text          = userInput,
            modality      = "text",
            language      = "en",
            participantId = "user1"
        }
    },
    parameters = new
    {
        projectName     = projectName,
        verbose         = true,
        deploymentName  = deploymentName,
        stringIndexType = "TextElement_V8"
    }
};

string json = JsonSerializer.Serialize(requestBody, new JsonSerializerOptions { WriteIndented = true });

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", subscriptionKey);
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

using var content = new StringContent(json, Encoding.UTF8, "application/json");
HttpResponseMessage response = await httpClient.PostAsync(endpoint, content);
string responseBody = await response.Content.ReadAsStringAsync();

Console.WriteLine("===== RESPONSE =====");
Console.WriteLine(responseBody);

4.5 Custom Question Answering

Custom Question Answering Workflow

flowchart TD
    A["Existing data\nPDF, Word, URL, FAQ"] --> B["Train the model\nin Language Studio"]
    B --> C["Deploy to production\nHTTP Endpoint"]
    C --> D{Client}
    D -->|Question| C
    C -->|Answer + score| D
    D --> E[Chatbot / Website]

Supported Content Sources

REST API Call — Question Answering

POST https://{endpoint}/language/:query-knowledgebases?projectName={project}&deploymentName={deployment}&api-version=2021-10-01
Content-Type: application/json
Ocp-Apim-Subscription-Key: {your-key}

{
  "question": "What is Azure AI Search?",
  "confidenceScoreThreshold": 0.5
}

Response:

{
  "answers": [
    {
      "answer": "Azure AI Search is a cloud search service...",
      "confidenceScore": 0.9,
      "id": 1
    }
  ]
}

C# SDK Example — Question Answering

using Azure;
using Azure.AI.Language.QuestionAnswering;

Uri endpoint = new Uri("https://{endpoint}.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("{your-key}");

string projectName    = "docs-qa-knowledge";
string deploymentName = "production";
string question       = "What sources are used in this knowledge base?";

QuestionAnsweringClient client   = new QuestionAnsweringClient(endpoint, credential);
QuestionAnsweringProject project = new QuestionAnsweringProject(projectName, deploymentName);

Response<AnswersResult> response = client.GetAnswers(question, project);

foreach (KnowledgeBaseAnswer answer in response.Value.Answers)
{
    Console.WriteLine($"Q: {question}");
    Console.WriteLine($"A: {answer.Answer}");
}

4.6 Multi-turn Conversation

Concept

A multi-turn conversation (guided conversation) allows the AI to retain previous context and guide the user through a sequence of steps.

Multi-turn Flow Example

User    : "Tell me about your return policy."
Chatbot : "Do you want to know about online purchases or in-store returns?"
User    : "Online purchases"
Chatbot : "For online purchases, you have 30 days to return..."
          [Next prompt] → "Would you like to know about refund timelines?"

Follow-up Prompt Architecture

Parent question: "What is Azure AI Language?"
    │
    ├── Follow-up: "Do you want to know which content sources we use?"
    │       └── Answer: "We are using multiple web pages, Word and PDF documents."
    │               └── Follow-up: "Do you like to know about additional resources?"
    │
    └── Follow-up: "What are the main APIs available?"

Best Practices

• Keep each turn clear and relevant
• Avoid long, nested chains that disorient the user
• Use follow-up prompts for clarification
• Group related questions under the same parent topic
• Test conversational paths before publishing

4.7 Alternate Phrasing and Chit-chat

Alternate Phrasing

Allows multiple phrasings to trigger the same answer.

Example:

• “How can I return an item?” ← main question
• “Can I return this?”
• “What is your return policy?”
• “Je veux retourner un article.” (multilingual)

Chit-chat

Predefined conversational responses for small talk.

Best Practices

• Add at least 3 to 5 alternate phrasings per key question
• Analyze logs to understand how users actually phrase their questions
• Verify that the chit-chat tone matches the organization’s brand image
• Retrain and republish after each phrasing or chit-chat addition

4.8 Knowledge Base Export / Import

Use Cases for Export

Export Formats

• Excel (.xlsx) — Tabular format, easy to edit
• TSV (Tab-Separated Values)

Exported Content

• Q&A pairs
• Alternate phrasings
• Follow-up prompts
• Metadata (topics, chit-chat, source references)

Best Practices

• Always export before a major structural change
• Use timestamped file names (qa-backup-2025-06-01.xlsx)
• Secure exports with RBAC and encryption
• Regularly test imports to validate the restore process

4.9 Multilingual Question Answering Solution

Two Approaches for Multilingual Support

┌─────────────────────────────────────────────────────────────────┐
│  Approach 1: One project per language                           │
│                                                                 │
│  User EN ──▶ Language detection ──▶ EN project                 │
│  User ES ──▶ Language detection ──▶ ES project                 │
│  User FR ──▶ Language detection ──▶ FR project                 │
│                                                                 │
│  ✅ Full editorial control                                      │
│  ❌ Maintenance overhead (N projects)                           │
└─────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────┐
│  Approach 2: Single project + machine translation               │
│                                                                 │
│  Question ES ──▶ Azure Translator (ES→EN) ──▶ EN project       │
│                                          ──▶ EN answer         │
│                                          ──▶ Azure Translator  │
│                                              (EN→ES)           │
│                                          ──▶ ES answer         │
│                                                                 │
│  ✅ Single project to maintain                                  │
│  ❌ Machine translation quality                                 │
└─────────────────────────────────────────────────────────────────┘

C# Example — Approach 2: Spanish Question via English Knowledge Base

using Azure.AI.Translation.Text;
using Azure.AI.Language.QuestionAnswering;

// Azure Translator credentials
string translatorKey      = "{your-translator-key}";
string translatorEndpoint = "https://{translator}.cognitiveservices.azure.com/";
string region             = "eastus";

// Question in Spanish
string spanishQuestion = "¿Qué es Azure AI Language?";

// 1. Translate question ES → EN
var translatorCredential = new AzureKeyCredential(translatorKey);
var translatorClient = new TextTranslationClient(translatorCredential,
    new Uri(translatorEndpoint), region);

var translationResponse = translatorClient.Translate(
    targetLanguage: "en",
    content: new[] { spanishQuestion },
    sourceLanguage: "es"
);
string englishQuestion = translationResponse.Value[0].Translations[0].Text;

// 2. Query the knowledge base in English
var qaClient  = new QuestionAnsweringClient(new Uri("{qa-endpoint}"), new AzureKeyCredential("{qa-key}"));
var qaProject = new QuestionAnsweringProject("docs-qa-knowledge", "production");
var qaAnswer  = qaClient.GetAnswers(englishQuestion, qaProject).Value.Answers[0].Answer;

// 3. Translate answer EN → ES
var answerTranslation = translatorClient.Translate(
    targetLanguage: "es",
    content: new[] { qaAnswer },
    sourceLanguage: "en"
);
string spanishAnswer = answerTranslation.Value[0].Translations[0].Text;

Console.WriteLine($"Q (ES): {spanishQuestion}");
Console.WriteLine($"A (ES): {spanishAnswer}");

4.10 Custom Translator

When to Use Custom Translator?

Custom Translator Workflow

flowchart TD
    A["Bilingual documents\nEN + FR parallel"] --> B["Create a workspace\nin Custom Translator"]
    C["Phrase dictionary\nEN → FR"] --> B
    B --> D["Create a project\n+ choose the domain"]
    D --> E["Upload Training Sets\n+ Test Sets + Dictionary Sets"]
    E --> F["Train the model\nFull training"]
    F --> G[Evaluate with BLEU Score]
    G -->|Score insufficient| E
    G -->|Score acceptable| H["Deploy the model\nREST Endpoint"]
    H --> I["Clients use\nthe category ID"]

BLEU Score

The BLEU Score measures the difference between a machine translation and a human reference translation.
A higher score indicates better translation quality.

Minimum Training Requirements

• 10,000 sentence pairs minimum to train a Custom Translator model

C# Example — Standard vs Custom Translation

using Azure;
using Azure.AI.Translation.Text;

string translatorKey      = "{your-key}";
string translatorEndpoint = "https://{translator}.cognitiveservices.azure.com/";
string region             = "eastus";
// Category ID of the custom model
string categoryId         = "8edcf1bf-e36f-4c84-ad72-03d67d8292d4-TECH";

string source = "You can use an Azure network security group to filter network traffic " +
                "between Azure resources in Azure virtual networks.";

var credential = new AzureKeyCredential(translatorKey);
var client     = new TextTranslationClient(credential, new Uri(translatorEndpoint), region);

// Standard translation (generic model)
var defaultResponse = client.Translate(
    targetLanguage: "fr-FR",
    content: new[] { source },
    sourceLanguage: "en-US"
);
string defaultTranslation = defaultResponse.Value[0].Translations[0].Text;

// Custom translation (model trained with NSG dictionary)
var customResponse = await client.TranslateAsync(
    targetLanguages: new[] { "fr-FR" },
    content: new[] { source },
    category: categoryId
);
string customTranslation = customResponse.Value[0].Translations[0].Text;

Console.WriteLine($"Source           : {source}");
Console.WriteLine($"Standard transl. : {defaultTranslation}");
Console.WriteLine($"Custom transl.   : {customTranslation}");
// The custom translation will use "NSG" (defined in dictionary)
// instead of a generic translation

5. References and Resources

Module 1 — Analyze and Translate Text

Module 2 — Process and Translate Speech

Module 3 — Custom Language Models

📌 Security reminder: Never store API keys in source code.
Use Azure Key Vault to manage secrets in production and read them dynamically at runtime.

Document generated from the AI-102 course “Implement Natural Language Processing Solutions”

Search Terms

ai-102 · implement · natural · language · processing · azure · ai · services · artificial · intelligence · generative · custom · api · rest · speech · call · clu · model · sdk · translation · question · answering · detection · architecture