Language model text analysis: extraction, sentiment, and translation
Three engines read the same paragraph
Pick the engine by the shape of the answer you need, not by how hard the text looks.
A support email arrives: "Our Contoso Brew 300 stopped heating on 14 March. Karin Weber has called 555-0176 twice and is losing patience." Three different useful things can come out of that one paragraph. A list of the named things in it, each with the exact character position where it appeared. A record with your own columns filled in: product, fault, severity, promised remedy. Or the same email in German for the regional desk. On Azure those are three engines, not three prompts to one model.
The three engines
Azure AI Language prebuilt tasks. Azure AI Language[1] exposes a set of ready-trained text tasks through one runtime endpoint. Each task has a published label set you cannot extend and a fixed response shape you can code against: entity recognition, entity linking, key phrase extraction, sensitive-information detection, sentiment analysis, and summarization, among others. You send documents and a task kind; you get that task's response object back.
A Foundry chat model with structured outputs. When the categories you need are not in anybody's published list, the extraction moves to a model in Microsoft Foundry and the guarantee moves into the request. Structured outputs[2] let you attach a JSON Schema to a chat completion so the reply comes back in the shape you declared. Your taxonomy, your field names, your enum values.
Azure Translator. Azure Translator[3] does one thing: it takes text in one language and returns it in another. It does not classify, summarize, or extract, and the controls that decide whether its output is usable are request parameters rather than prompt wording.
A naming note before we go further. Current Microsoft Learn product-doc titles render these as "Azure Language in Foundry Tools" and "Azure Translator in Foundry Tools", part of the consolidation into Microsoft Foundry. Azure AI Language and Azure Translator are the same services under their established names, and this page uses those names throughout.
What this page owns
Everything here starts once the text already exists as characters. The sibling page on speech solutions owns anything that arrives as, or leaves as, audio, which includes spoken translation. The document content extraction page owns getting text and layout out of a PDF, a scanned form, or a Word file in the first place. An email body, a chat transcript that is already text, a product review, a contract clause pasted into a field: those are this page.
Figure 1 below traces one input through all three engines and shows what each hands back. Read it left to right and notice that the difference is never how clever the engine is; it is what the response object contains.
So the selection question is mechanical. Does a published label set already describe what you need, and do you want offsets? Take the prebuilt task. Do you need field names and enum values that only exist in your domain? Take a model with a strict schema. Is the job language to language on text? Take Translator.
What each prebuilt extraction task returns
Choosing among the prebuilt extraction tasks is choosing what the response object contains. Four tasks compete for the same-sounding requirement "pull the important things out of this text", and they return four different things.
Named entity recognition
Named entity recognition[4], usually written NER, identifies mentions in text and types each one against a preset category and subcategory list: Person, Location, Organization, Quantity, DateTime and others. Every returned mention carries an offset (where it starts), a length, and a confidenceScore. Those three fields are the reason NER is the right task whenever something downstream has to highlight, crop, mask, or index the exact span rather than merely know a name was present.
Entity linking
Entity linking[5] is a separate task, not a NER option. It resolves an ambiguous mention to a single knowledge-base entry and returns that entry's reference URL. The predictable misread is worth killing on sight: NER alone never returns a knowledge-base identifier. If the requirement is deciding whether "Mars" in a document means the planet or the confectionery company, NER will tell you it is an entity and entity linking will tell you which one.
Key phrase extraction
Key phrase extraction[6] surfaces the main talking points of a document as a flat list of phrases. No entity category, no character offset, no relevance ranking. That makes it a good cheap signal for tag clouds, coarse topic routing, and "what is this document about" dashboards, and a poor fit the moment a consumer needs the type of a value or the place it appeared. Populating form fields, driving redaction, and filtering a search facet all need type or position, so they belong to entity recognition or to schema-driven generative extraction.
Custom named entity recognition
When your domain has entity types the preset list does not carry, part numbers in a specific format, internal case identifiers, clause types in a contract, custom NER[7] adds them. The cost is a project lifecycle rather than a parameter: an authoring project holding human-labeled documents, a training run over those labels, and an explicit deployment that exposes a runtime prediction endpoint you then call. Prebuilt entity recognition requires none of that; you call the runtime immediately with the entity recognition task kind. There is no configuration-only or prompt-only shortcut that adds a new type to the prebuilt model.
Figure 2 below puts one sentence through all four tasks so the four response shapes sit side by side. The published category list shown there is a sample of the preset categories rather than the whole list, which is long and differs by input language.
The takeaway is a two-question filter. Does the consumer need to know where the value was, or which real-world thing it is? That rules key phrase extraction out. Is the type you need on the published list? If yes, prebuilt NER; if no, either custom NER with labeled data or a generative extraction with a schema.
Calling the analyze-text runtime
One synchronous call runs one task; the asynchronous job endpoint runs several tasks over the same documents in one submission.
That single sentence decides the shape of most Azure AI Language pipelines. If a corpus needs entity recognition, key phrase extraction, and sensitive-information detection, three synchronous calls send the same documents across the wire three times. Submitting them asynchronously[8] sends the corpus once and attaches a list of tasks to it.
Request body: three tasks over one document collection
{
"displayName": "Support mail enrichment",
"analysisInput": {
"documents": [
{ "id": "1", "language": "de", "text": "Unsere Contoso Brew 300 heizt nicht mehr." }
]
},
"tasks": [
{ "kind": "EntityRecognition" },
{ "kind": "KeyPhraseExtraction" },
{ "kind": "PiiEntityRecognition" }
]
}
The tasks array is what makes this a batch: each element names one kind, and every task runs over every document in analysisInput.documents. The submission returns immediately with an operation location you poll; the task results arrive together when the job completes. Notice language on the document rather than on the request, because the collection can mix languages.
The language field is not optional in practice
Prebuilt Language tasks accept a per-document language code, and when none is supplied the analysis defaults to English[9]. Nothing errors. A German document analyzed as English simply comes back with fewer entities and weaker phrases, which reads in production like a model-quality problem and is actually an unset field. Supported entity categories also differ by input language[10], and categories that are not enabled by default for a given language have to be requested explicitly through the task's category parameter.
Results have a 24-hour life
Asynchronous results are available for retrieval for 24 hours from the time the request was ingested, and after that window they are purged and can no longer be fetched. The job identifier is a handle on a temporary result, not a storage key. Any pipeline that will want those entities next week writes them somewhere itself.
Figure 3 below puts the two call paths side by side, with the polling loop and the 24-hour window drawn only on the asynchronous lane where they apply.
So the mechanics reduce to three habits: batch tasks that share a corpus, always set the language code, and persist results before the day is out.
Schema-driven extraction with structured outputs
Setting strict to true is what turns a JSON Schema from a suggestion into a guarantee.
There are two ways to ask a Foundry chat model for JSON, and only one of them binds. JSON mode, response_format of type json_object, promises that the reply parses as valid JSON and nothing more; the model can still rename a field, drop one, or invent one. Structured outputs[2], response_format of type json_schema with strict set to true, force the reply to conform to the schema you supplied. That difference is what makes generative entity, topic, and field extraction machine-consumable without a defensive parsing layer that guesses.
Anatomy of a strict response_format block
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "support_case",
"strict": true,
"schema": {
"type": "object",
"properties": {
"product": { "type": "string" },
"fault": { "type": "string" },
"severity": { "type": "string", "enum": ["low", "medium", "high"] },
"promised_remedy": { "type": ["string", "null"] }
},
"required": ["product", "fault", "severity", "promised_remedy"],
"additionalProperties": false
}
}
}
Three rules of strict mode are visible in that listing. Every property appears in the required array. Every object sets additionalProperties to false. And there is no genuinely optional field: promised_remedy is emulated as optional by giving it a union type that includes null while still being listed in required. Output key ordering follows the order of the schema you send, so the listing above produces product, fault, severity, promised_remedy in that order.
What the schema will not do for you
The supported subset of JSON Schema covers string, number, boolean, integer, object, array, enum, and anyOf, with the caveat that the root object itself cannot be an anyOf. Definitions through $defs and recursive references are supported. A schema may declare at most 100 object properties across five levels of nesting.
What is not honoured is most of the validation vocabulary: minLength, maxLength, pattern, and format on strings, minimum, maximum, and multipleOf on numbers, and minItems, maxItems, and uniqueItems on arrays. The model will return a string where you asked for a string; it will not guarantee that string matches your regular expression. Range checks, format checks, and array bounds run in your own code after parsing. Figure 4 below draws that split so the boundary is hard to forget.
Strict tool arguments cost you parallel calls
Structured outputs apply to tool definitions as well: strict: true on a function forces the generated arguments to match the parameter schema exactly. The catch is that structured outputs are not supported together with parallel function calling, so parallel_tool_calls must be set to false whenever strict tool schemas are in use. Leaving parallel calls enabled and assuming the strict argument contract still holds for every emitted call is the failure worth remembering.
Surfaces where structured outputs do not apply
Microsoft documents structured outputs as unsupported with Azure OpenAI On Your Data (the bring-your-own-data scenarios), with the Assistants and Foundry Agent Service surfaces, and with the gpt-4o-audio-preview and gpt-4o-mini-audio-preview models. The design consequence is concrete: an extraction step that must return a guaranteed schema calls chat completions directly rather than routing through an agent run, even when the rest of the workflow is agentic.
Pulling it together: strict mode gives you names, types, and presence. Everything about the values remains your responsibility, and the guarantee only exists on the surfaces that support it.
Full chat completions call with a strict extraction schema
The listing below is the whole request and the whole reply for the support-mail extraction used in this section. Only the model deployment name and endpoint are placeholders.
Request
POST https://<your-resource>.openai.azure.com/openai/deployments/<your-deployment>/chat/completions?api-version=2024-10-21
Content-Type: application/json
api-key: <your-key>
{
"messages": [
{
"role": "system",
"content": "Extract the support case fields from the user message. Use null for promised_remedy when the message promises nothing."
},
{
"role": "user",
"content": "Our Contoso Brew 300 stopped heating on 14 March. Karin Weber has called twice and is losing patience. We told her an engineer would visit this week."
}
],
"response_format": {
"type": "json_schema",
"json_schema": {
"name": "support_case",
"strict": true,
"schema": {
"type": "object",
"properties": {
"product": { "type": "string" },
"fault": { "type": "string" },
"severity": { "type": "string", "enum": ["low", "medium", "high"] },
"promised_remedy": { "type": ["string", "null"] }
},
"required": ["product", "fault", "severity", "promised_remedy"],
"additionalProperties": false
}
}
}
}
Reply (message content only, other response fields omitted)
{
"product": "Contoso Brew 300",
"fault": "stopped heating",
"severity": "high",
"promised_remedy": "engineer visit this week"
}
The reply is guaranteed to carry exactly these four keys, in this order, with severity drawn from the declared enum. What it is not guaranteed to do is keep fault under any particular length or make promised_remedy parse as a date, because maxLength and format are among the keywords strict mode ignores. If a message promised nothing, promised_remedy comes back as null rather than being absent, which is the whole point of the nullable union type.
What sentiment analysis can and cannot label
Sentiment analysis[11] has exactly three labels, and no amount of configuration adds a fourth meaning.
The task returns confidence scores between 0 and 1 for positive, neutral, and negative, for the document as a whole and for every sentence inside it, then assigns the highest-scoring label at each level. At document level there is also a derived mixed label, which appears when a document contains both positive and negative sentences. Scoring at two levels matters more than it sounds: a long review whose document label lands on neutral can still contain individually negative sentences, and a triage rule that reads only the document label never sees them.
Opinion mining attaches an opinion to its target
Opinion mining is an option on the sentiment task, not a separate service. Switching it on performs aspect-based sentiment analysis: it links each expressed sentiment to the concrete thing it is about, "the room", "the staff", "battery life", and returns target and assessment pairs. Base sentiment analysis returns only a label per sentence with no attribution to a product or service attribute, so a report that has to say what customers disliked rather than how many were unhappy needs opinion mining enabled.
Figure 5 below shows the three levels together: the document label on top, the per-sentence labels under it, and the target and assessment pairs that opinion mining hangs off the sentences carrying opinions. Sentences that express no opinion about a specific target simply have nothing below them.
The tone gap, and how to close it
None of these labels has any vocabulary for tone or emotion: frustration, urgency, politeness, sarcasm, escalation risk. This is the trap worth debunking on the spot. "Negative" cannot distinguish an angry customer from a disappointed one, and it cannot flag an urgent but perfectly polite escalation, because it is one axis with three labels. Enabling opinion mining does not add emotion classes either, since it returns target and assessment pairs on that same three-label scale. Lowering a confidence threshold changes which label wins, not which labels exist.
Detecting tone means defining the taxonomy yourself and then classifying against it. Three approaches, in rough order of how much machinery they need:
| Approach | What you define | When it fits |
|---|---|---|
| Chat model with a constrained enum | The tone classes, as an enum in a strict schema | Per-message or per-ticket labelling at scale |
| Evaluator or LLM-judge rubric | A scoring rubric applied to whole conversations | Quality review over transcripts, offline |
| Content Understanding audio analyzer with custom generative fields | The fields to generate from the audio | Tone carried by spoken delivery rather than wording |
The first row is the one that belongs on this page, and it is the structured-outputs mechanism from the previous section pointed at a classification job rather than an extraction job. The third row applies when the signal is in how something was said, which puts it on the speech solutions page rather than here.
So the boundary to carry into the exam: sentiment for polarity, opinion mining for polarity plus target, and a taxonomy of your own for anything that has a name other than positive, neutral, or negative.
Redacting sensitive information from text
The sensitive-information task hands back the masked copy of the text; you do not assemble it yourself.
That is the part people miss. PII detection[9] evaluates unstructured text for predefined personal information (PII, for personally identifiable information) and health information categories, and returns two things in one response: the entity list, each item carrying category, offset, length, and confidenceScore, and a redactedText string in which every detected span is already masked. Running generic entity recognition and hand-building the masked string throws away the category-aware spans the task already produced.
Called synchronously the feature is stateless. No data is stored in the resource and results come back in the response, which is what lets a pipeline log entity metadata for audit and forward only the redacted copy downstream. Called asynchronously it inherits the 24-hour retrieval window described earlier for jobs.
The redaction policy decides what survives
The redactionPolicies parameter, introduced in the 2025-11-15-preview API version, sets how detected spans are masked. It accepts four policy kinds, and one request can carry a default policy plus per-entity overrides:
| Policy kind | What redactedText looks like | Offsets and length |
|---|---|---|
characterMask (default) | The span replaced by a repeated character, ******** | Preserved |
entityMask | A typed placeholder, [PERSON_1] | Not preserved |
noMask | No redactedText field is returned at all | Not applicable |
syntheticReplacement | A realistic but fictitious value, Sam Johnson | Not preserved |
Only length-preserving character masking keeps downstream character offsets valid. If a later stage indexes into the original document by offset, or diffs the redacted copy against the original, entityMask and syntheticReplacement silently break it because the replacement is a different length from what it replaced. The characterMask policy also takes an optional redactionCharacter field when the default asterisk is inconvenient. Synthetic replacement is currently a preview anonymization capability, so treat it as a test-data generator rather than a production control until it reaches general availability.
Figure 6 below runs one sentence through all four policies so the trade-off is visible in the output rather than in a rule.
Narrowing what gets detected
The task attempts the defined entity categories for the input language, and the optional piiCategories parameter restricts the response to the categories you name. The same parameter is how you request categories that are not enabled by default for your input language. One gotcha: if you specify categories without including default, the API returns only the categories you listed.
The design rule that falls out: choose the policy from what the next stage needs, not from what looks most thoroughly redacted. Offsets to preserve means characterMask; a human-readable transcript means entityMask; metadata only, with the original held elsewhere, means noMask.
Severity scoring for harmful text
Harm screening answers a different question from anything above it on this page, and it uses a different scale to do it.
Sentiment tells you how a passage feels. Sensitive-information detection tells you which spans must be masked. Azure AI Content Safety[12] tells you how severely a passage falls into a harm category, and it does that for four categories: Hate, Sexual, Violence, and SelfHarm.
Two properties of the scoring matter for design decisions. First, the text model rates on the full 0 to 7 severity scale, and the API can return either that full scale or a trimmed one in which each adjacent pair of levels collapses to a single value, giving 0, 2, 4, and 6. Text scoring and multimodal image-with-text scoring both offer the eight-level output. A threshold policy built on the assumption that only four buckets exist cannot express the difference between a level 4 finding and a level 5 one, which is exactly the granularity a tiered review queue needs.
Second, classification is multi-label. One passage can be flagged under more than one category at once, so a routing rule reads the whole set of category severities rather than picking a single winning category the way sentiment picks a single winning label.
What this page does not cover is what you then do with a severity: configuring content filters on a deployment, choosing block thresholds, running blocklists, and the annotation and streaming behaviour of the filter pipeline all belong to the responsible AI pages of this guide. Here the point is narrower. When an exam stem says a workload must rate text on how harmful it is, that is Content Safety and its severity levels, not a sentiment score and not an entity category.
Summarization: verbatim, generated, and per aspect
Summarization[13] forks on one question: may the summary contain words that are not in the source?
Extractive keeps every word; abstractive writes new ones
Extractive summarization produces a summary by selecting salient sentences from the source and returning each one with two extras. A rank score indicates how relevant the sentence is to the main topic, and you can choose whether the sentences come back in the order they appear in the document or in rank order. Positional information gives the start position and length of each extracted sentence. Every word in the result is verbatim and every line maps back to a location in the input, which is what compliance reviewers usually mean when they say the summary must be traceable.
Abstractive summarization generates concise, coherent sentences that are not verbatim extracts. Instead of per-sentence offsets it returns a contextual input range, the range within the input that was used to generate each summary text; a long input can be segmented so several groups of summary texts come back, each with its own range. If the requirement is that no wording may be invented, abstractive is the wrong branch no matter how much better it reads.
Conversations are summarized per aspect
Conversation summarization takes structured, speaker-tagged conversational input rather than a plain text block, and it is requested per aspect. The documented aspects[14] are issue and resolution for contact-centre calls, recap for a single-paragraph summary of the whole conversation, and chapterTitle together with narrative, which segment a long conversation and title and summarize each segment. Text summarization accepts only a plain text block and has no aspect concept at all, so flattening a call transcript into one string and still expecting separated issue and resolution output does not work.
A third genre, native document summarization, is in preview and accepts documents in their original format, currently .txt, .pdf, and .docx, with the same extractive and abstractive approaches.
Figure 7 below lays the genres, approaches, and output shapes out in three columns so the mapping is one glance rather than three paragraphs.
Jobs, and the 24-hour window
Summarization is processed as an asynchronous job. As with the other job-based tasks described earlier, the output is available for retrieval for 24 hours and is then purged, so the pipeline persists what it needs.
The retirement, and what replaces it
Microsoft has published a retirement date for Summarization in Azure AI Language of 31 March 2029, and directs both existing workloads and all new projects to Microsoft Foundry models for natural-language understanding. For a green-field Foundry build, the task-specific summarization API is a migration path for legacy code rather than the recommended default, even though it looks like the purpose-built choice.
That lines up with a second limit. Domain summarization work often carries output requirements the prebuilt task cannot express: mandatory sections, a fixed tone, named clause types that must be called out, citations back to the source. The prebuilt API exposes summary-length and style controls over content it chooses itself; it has no surface for "always surface the indemnity clause". A Foundry model steered by a system prompt plus a strict JSON schema, the mechanism from the structured-outputs section above, delivers that control.
So: extractive when traceability is the requirement, abstractive when readability is, conversation aspects when the input has speakers, and a prompted model when the shape of the summary is itself a requirement.
Choosing a Translator surface
What you hand Azure Translator decides which surface you are on: strings go to the text translation endpoint, one file goes to synchronous document translation, and a library of files goes to asynchronous batch.
Strings
The text translation API[15] takes a JSON array of strings and returns a translation array, one result per input string, with one entry per target language. Repeat the to parameter to translate into several languages in the same call. Because it takes and returns strings, it cannot round-trip a .docx or a .pptx: extracting the text from a file and looping it through this endpoint discards exactly the layout and formatting that document translation exists to preserve.
Files
Document translation[16] has two processes, and they differ in more than throughput.
Asynchronous batch handles multiple documents and large files. It requires an Azure Blob Storage account with separate source and target containers, and a way to authorize access to those storage URLs: either shared access signature (SAS) tokens or managed identities. You upload sources, submit the batch job, poll job status and per-document status, then download the translated files from the target container. Batch is also the path that accepts Adobe PDF, where optical character recognition (OCR) extracts and translates the text of a scanned PDF while retaining the original layout.
Synchronous single-file accepts one document per request, needs no storage account, and returns the translated document directly in the response. Its supported formats are .txt, .tsv/.tab, .csv, .html/.htm, .mhtml/.mht, .pptx, .xlsx, .docx, .msg, and .xlf. Both processes preserve the original layout and formatting, and both can apply a custom translation model and a custom glossary.
The inversion worth naming out loud, because it reads backwards to most people: it is the asynchronous batch mode that requires the blob source and target containers, not the synchronous one, and synchronous accepts only a single document per request. Figure 8 below draws the three call paths so the storage requirement sits visibly on one lane only.
Translator against a chat model
A Foundry chat model can also translate, and there are jobs where it is the better tool. It can be steered on register, audience, and terminology inside the prompt ("formal German for a legal notice, keep product names in English"), and it can fuse translation with another task, translating and summarizing a review in one call.
What it does not give you is the rest of Translator's contract: layout-preserving round-trip of an Office file or a scanned PDF, per-document job status over a library, a trained glossary applied the same way every time, or the X-mt-system response header that reports whether a custom system actually served the request. So the split is not quality against quality. Use Translator when the artifact is a file or the terminology has to be provable; use a model when the requirement is stylistic control or translation fused with another job.
Translator request parameters that change the output
Translator's quality controls are query-string parameters, not prompt wording. Six of them decide whether a translation is publishable, and each has a default that is worth knowing because the defaults are permissive.
| Parameter | Values | Default | What it does |
|---|---|---|---|
category | a Custom Translator category ID | general | Routes the request to your trained custom system |
allowFallback | true, false | true | Whether a missing custom system silently falls back to the general one |
textType | plain, html | plain | Whether markup is preserved or translated as prose |
profanityAction | NoAction, Marked, Deleted | NoAction | Whether profanity passes through, is marked, or is removed |
profanityMarker | Asterisk, Tag | Asterisk | How marked profanity is rendered |
from | a source language code | autodetect | Required when the dynamic dictionary is used |
Proving a custom system was used
A trained Custom Translator[17] system is invoked by passing its category ID in category. The trap is allowFallback, which defaults to true: the request quietly falls back to the general system whenever no custom system exists for that language pair, and the caller sees a perfectly fluent translation that ignored every trained term. Setting allowFallback=false makes the request return HTTP 400 instead of a non-custom translation. If a chain through a pivot language is needed, every system in the chain has to be custom and share the same category. In a regulated workflow that 400 is the feature, not the bug: it is how you prove every returned string came from the trained terminology. The X-mt-system response header is the second check, reporting Custom when at least one custom system served the request.
Pinning one phrase against training a system
The dynamic dictionary[18] supplies a known rendering for a single span inline:
The word <mstrans:dictionary translation="wordomatic">wordomatic</mstrans:dictionary> is a dictionary entry.
Three constraints ride with it. It is case-sensitive. It requires the from parameter, because source-language autodetection is not allowed alongside it. And Microsoft documents it as safe only for proper nouns such as personal names and product names. Injecting this markup for an entire glossary is the wrong shape of solution: it costs you autodetection and it does not use context the way a trained system does. Systematic terminology and style control belong in Custom Translator, which learns those choices from in-context training data.
Markup and profanity
Setting textType=html tells Translator the payload is well-formed markup, so tags are preserved rather than translated as prose, and any element carrying class="notranslate" is returned in its source language[19]. That combination is how boilerplate, code samples, brand names, and legal identifiers stay untouched on a translated page. Submitting HTML under the default plain text type translates the markup itself and corrupts the document.
Profanity passes through untouched by default. Deleted removes the profane words from the output with no replacement, while Marked replaces them, with asterisks by default or wrapped in <profanity> tags when profanityMarker=Tag. The distinction matters for moderation: Deleted destroys the evidence that anything was there, whereas Marked with Tag leaves a signal a downstream workflow can detect and act on.
Exam-pattern recognition
The stems on this topic are almost always a requirement in disguise. Read for the output the scenario needs, then map it.
"Must know both the entity type and where in the document each value appeared." Prebuilt entity recognition. Key phrase extraction is the distractor and it loses on both counts: no category and no offset. Entity linking loses because the requirement is not disambiguation.
"Decide whether a mention refers to the company or the planet." Entity linking, because it resolves the mention to one knowledge-base entry and returns its reference URL. Named entity recognition tells you the span is an entity and never returns a knowledge-base identifier.
"Add a new domain-specific entity type." Custom NER, and the correct answer includes labeling documents, training, and deploying. Any option implying a configuration switch or prompt-only change to the prebuilt model is wrong.
"Output must always contain the same fields with the same types." A chat model with response_format of type json_schema and strict: true. JSON mode (json_object) is the near-miss distractor: it removes parse errors but still permits renamed, missing, or invented fields.
"The extraction runs inside an agent and must return a guaranteed schema." The trick is that structured outputs are not supported on the Assistants and Foundry Agent Service surfaces, nor with On Your Data, nor with the audio-preview models. The correct design calls chat completions directly.
"Detect frustration, urgency, or escalation risk." Not sentiment analysis, and not opinion mining. The answer defines a tone taxonomy and classifies into it, typically a model constrained to an enum through a strict schema.
"Summary must not invent wording and must map back to the source." Extractive summarization, which returns ranked verbatim sentences with start position and length. Abstractive is the fluent-sounding wrong answer.
"Separate the issue from the resolution in a call transcript." Conversation summarization with the issue and resolution aspects, on speaker-tagged input. Flattening the transcript for text summarization is the distractor.
"Mask personal data but keep character offsets valid downstream." The sensitive-information task with the characterMask policy, which preserves original length and offsets. entityMask is the trap because typed placeholders change the length.
"Rate how harmful a passage is." Azure AI Content Safety severity levels, on the 0 to 7 scale (or the trimmed 0, 2, 4, 6 form), multi-label across Hate, Sexual, Violence, and SelfHarm. A negative sentiment score is not a harm severity.
"Translate a library of PDFs and keep the layout." Asynchronous batch document translation over Blob Storage source and target containers. Looping text through the /translate endpoint is the distractor, and so is the synchronous single-file path, which takes one document per request and does not accept PDFs.
"Prove every translated string used the trained glossary." allowFallback=false, which returns HTTP 400 rather than a general-system translation. Leaving the default true is exactly the silent failure the stem is testing.
"A green-field Foundry solution needs summaries." Watch for the retirement: Summarization in Azure AI Language retires on 31 March 2029 and Microsoft directs new projects to Foundry models. "Use the purpose-built summarization API" is the plausible-sounding wrong answer.
"Results are read from the job a few days later." Wrong by construction. Asynchronous Language job output is retrievable for 24 hours from ingestion and then purged; the correct answer persists the results.
Choosing between the three engines that read text
| Requirement | Azure AI Language prebuilt task | Foundry model with structured outputs | Azure Translator |
|---|---|---|---|
| Label set | Published categories you cannot extend, except through custom NER | Any enum you declare in the schema | Not a labeling service |
| Output shape | Fixed response object per task kind | The JSON Schema you supply, when strict is true | Translated strings, or translated files with layout preserved |
| Character offsets | Returned for entities, PII spans, and extractive summary sentences | Only if you declare them, and you must validate them yourself | Not applicable |
| Training or labeling | None for prebuilt tasks; labeled project, training run, and deployment for custom NER | None; steering is the system prompt plus the schema | Optional Custom Translator model trained on in-context data |
| How it is called | analyze-text synchronously for one task, or an async job for several tasks at once | Chat completions with response_format of type json_schema | translate for strings, document translation for files |
| Where it runs out | No vocabulary outside the published taxonomy, and no tone or emotion classes | No offsets, no ranking, and validation keywords such as pattern and minimum are ignored | Cannot classify, summarize, or extract; it only changes the language |
Decision tree
Sharp facts the exam loves — give these one last read before exam day.
Cheat sheet
Sharp facts the exam loves — scan these before test day.
- Structured outputs with json_schema and strict:true guarantee schema adherence; JSON mode only guarantees valid JSON
Setting response_format to {"type": "json_schema", "json_schema": {..., "strict": true}} forces a Foundry model to emit output that conforms to the JSON Schema you supply, which is what makes generative entity, topic, and field extraction machine-consumable. The older JSON mode (response_format of type json_object) guarantees only that the reply parses as valid JSON; it cannot guarantee the reply carries the fields, names, or types your extraction pipeline expects.
Trap Choosing JSON mode (json_object) for a schema-driven extraction job: it eliminates parse errors but still lets the model rename, omit, or invent fields.
7 questions test this
- You are building a Foundry entity-extraction service that reads support emails and returns a fixed record - customer_id, product, and issue_type - that a downstream ticketing system deserializes into
- A colleague configured a Foundry topic-tagging service in JSON mode (response_format json_object) to return a topics array and a sentiment field for each review. Every response is valid JSON, but down
- A logging pipeline in your Foundry project asks a gpt-4o deployment to summarize each incident into a JSON object whose keys are the distinct root causes the model discovers, so the property names dif
- A Foundry analytics job extracts each review's rating as an integer and sentiment as one of three enum labels from a gpt-4o deployment, then loads them straight into a typed database. Under JSON mode
- You extract structured JSON from insurance claims with a strict Foundry structured-outputs schema. To constrain values you added a regex pattern to the policy_number string, a minimum and maximum to t
- You are building an entity-extraction step in a Microsoft Foundry project where a gpt-4.1 deployment reads inbound support emails and must return each ticket's customer name, product, and severity as
- You must extract a fixed set of fields - entities, a topic label from a controlled list, and an overall sentiment - from free-text product reviews, and hand the result to a strongly typed downstream s
- A strict structured-outputs schema must mark every property required and set additionalProperties to false
In strict mode every property must appear in the object's required array and every object must set additionalProperties: false. There is no genuinely optional field: you emulate one by giving the property a union type that includes null (for example "type": ["string", "null"]) while still listing it in required. Output key ordering follows the order of the schema you send.
Trap Leaving a property out of required to make it optional — the schema is rejected rather than treated as an optional field.
7 questions test this
- Your Foundry extraction schema pulls resume fields into strict structured-outputs JSON. Most fields are always present, but middle_name is frequently absent in the source text. You need the analyzer t
- A logging pipeline in your Foundry project asks a gpt-4o deployment to summarize each incident into a JSON object whose keys are the distinct root causes the model discovers, so the property names dif
- A colleague's strict json_schema extracts an order object with a nested shipping_address object on a gpt-4.1 deployment. Every top-level property is listed in required and the root sets additionalProp
- A Foundry extraction step returns structured-outputs JSON that a downstream component serializes into a fixed-column export, and it expects the keys in a specific order: id, name, then status. The com
- Your strict json_schema extracts contact fields from resumes on a gpt-4.1 deployment. The name and email fields are always present, but middle_name is frequently absent from a candidate's document. Yo
- Your Foundry extraction analyzer sends a gpt-4o deployment a json_schema with strict set to true to pull invoice_number, vendor, and total from scanned receipts. The schema lists all three fields unde
- Your team defines a strict structured-outputs schema so a Foundry model extracts contract metadata - party_name, effective_date, and renewal_term - into machine-consumable JSON. The service rejects th
- Structured outputs support only a subset of JSON Schema and drop most validation keywords
The supported subset covers string, number, boolean, integer, object, array, enum, and anyOf (the root object cannot be anyOf), plus $defs and recursive references. Validation keywords are not honored: minLength, maxLength, pattern, and format on strings, minimum, maximum, and multipleOf on numbers, and minItems, maxItems, and uniqueItems on arrays. A schema may declare at most 100 object properties across five levels of nesting.
Trap Expecting the schema to enforce value ranges, regex patterns, or array bounds; those checks must run in your own code after parsing.
10 questions test this
- Your strict json_schema extracts an applicant's email as a string with format set to email and a submitted_on string with format set to date-time from a gpt-4o deployment. QA finds the model returns m
- Your Foundry extractor must tag each document with a topic drawn from a fixed controlled vocabulary of eight labels, and the downstream taxonomy service rejects any value outside that list. You are us
- You are designing a strict structured-outputs schema for a Foundry extractor that must return either a person entity or an organization entity, depending on the input. You wrote the schema so the root
- A colleague's strict json_schema extracts an order object with a nested shipping_address object on a gpt-4.1 deployment. Every top-level property is listed in required and the root sets additionalProp
- You extract structured JSON from purchase orders with a strict json_schema on a gpt-4.1 deployment. To keep bad data out of the ledger, the schema declares a currency string with a pattern for ISO cod
- A Foundry analytics job extracts each review's rating as an integer and sentiment as one of three enum labels from a gpt-4o deployment, then loads them straight into a typed database. Under JSON mode
- Your strict json_schema extracts contact fields from resumes on a gpt-4.1 deployment. The name and email fields are always present, but middle_name is frequently absent from a candidate's document. Yo
- Your Foundry extraction analyzer sends a gpt-4o deployment a json_schema with strict set to true to pull invoice_number, vendor, and total from scanned receipts. The schema lists all three fields unde
- You extract structured JSON from insurance claims with a strict Foundry structured-outputs schema. To constrain values you added a regex pattern to the policy_number string, a minimum and maximum to t
- Your team defines a strict structured-outputs schema so a Foundry model extracts contract metadata - party_name, effective_date, and renewal_term - into machine-consumable JSON. The service rejects th
- strict:true on a function tool constrains generated arguments but forbids parallel tool calls
Structured outputs also apply to tool definitions: setting strict: true on a function forces the generated arguments to match the parameter schema exactly. Structured outputs are not supported together with parallel function calling, so parallel_tool_calls must be set to false whenever strict tool schemas are in use.
Trap Leaving parallel tool calls enabled and assuming the strict argument schema still holds for every emitted call.
4 questions test this
- Your Foundry agent issues two independent lookups per turn and you enabled parallel tool calls to keep turn latency low. You now add strict to the function definitions so the model's generated argumen
- Your Foundry agent issues several tool calls per turn in parallel to keep latency low. A new requirement says one tool's generated arguments must exactly match its parameter schema, so you plan to set
- You define a function tool for a Foundry chat completion so the model's generated arguments always match your parameter schema, and you set strict to true on the function. The same request currently l
- You register a function tool on a Foundry chat model so it emits arguments for a downstream create_shipment API, and you set strict to true on the tool so the generated arguments always match its para
- Structured outputs are unsupported on the bring-your-own-data, Assistants/Agent Service, and audio-preview surfaces
Microsoft documents structured outputs as not supported with Azure OpenAI On Your Data (bring-your-own-data) scenarios, with the Assistants and Foundry Agent Service surfaces, and with the gpt-4o-audio-preview and gpt-4o-mini-audio-preview models. An extraction step that must return a guaranteed schema therefore calls chat completions directly rather than routing through an agent run.
Trap Designing an agent tool that relies on strict schema adherence from the agent run itself instead of from a direct model call.
- NER types a mention against a fixed category list; entity linking disambiguates it against a knowledge base
Prebuilt named entity recognition returns spans typed against a preset category and subcategory list (person, location, organization, quantity, and so on) with an offset, length, and confidence score. Entity linking is a separate task that resolves an ambiguous mention to a single knowledge-base entry and returns its reference URL; named entity recognition alone never returns a knowledge-base identifier.
Trap Reaching for named entity recognition when the requirement is to decide whether 'Mars' means the planet or the company — that disambiguation is entity linking.
9 questions test this
- You are building a compliance agent in a Microsoft Foundry project that scans vendor correspondence and must tag every organization, person, and location mentioned so reviewers can filter by category.
- You are building a market-intelligence agent in a Microsoft Foundry project that scans news articles about the automotive sector. The pipeline frequently encounters the token 'Mars' and must decide, f
- You are enriching a Microsoft Foundry knowledge-graph pipeline that ingests analyst reports. Company names appear in many surface forms - 'Microsoft,' 'Microsoft Corp,' and 'MSFT' - and you need every
- A document-search team in a Microsoft Foundry project wants to tag each indexed article with the categories of entities it contains, such as Person, Organization, and Location, so users can filter sea
- You are building an intake agent in a Microsoft Foundry project that processes incoming support emails. For each email the agent must highlight standard entities - people, organizations, locations, da
- A knowledge-graph team in a Microsoft Foundry project ran prebuilt named entity recognition over a corpus of company filings, expecting each detected organization to come back with a canonical knowled
- A developer on your team wants prebuilt Azure Language NER to start returning a new 'policy number' entity that is specific to your insurance product. They tried enabling it through the analyze-text r
- You are building a contracts-processing agent in a Microsoft Foundry project. The agent must extract a company-specific entity type - an internal 'master service agreement clause reference' - that doe
- Your team processes incoming insurance-claim emails in a Microsoft Foundry project and must automatically identify and categorize the people, organizations, locations, and monetary quantities that eac
- Key phrase extraction returns untyped, unpositioned talking points
Key phrase extraction surfaces the main talking points of a document as a flat list of phrases with no entity category, no character offset, and no relevance ranking. Whenever the downstream consumer needs typed, positioned values — populating form fields, driving redaction, or filtering a search facet — prebuilt entity recognition or a schema-driven generative extraction is required instead.
Trap Selecting key phrase extraction for a pipeline that must know both the entity type and where in the document each value appeared.
7 questions test this
- A Microsoft Foundry pipeline ingests scanned vendor purchase orders and must populate a structured record with named business fields, the purchase-order number, buyer, delivery date, and total, where
- Your Microsoft Foundry application analyzes analyst reports and must, for every company and place mentioned, record both the entity type and the exact character position where it appears so the UI can
- You are building a meeting-assistant agent in a Microsoft Foundry project that processes long call transcripts. Product wants each transcript surfaced with a compact set of topic chips - short phrases
- Your team operates a Microsoft Foundry project that logs customer chat transcripts. Before any transcript is stored, the pipeline must find sensitive values such as names, phone numbers, and email add
- Your team operates a Microsoft Foundry project that ingests tens of thousands of open-ended customer survey comments each week. Product managers want a weekly word cloud of the recurring themes people
- You maintain a Microsoft Foundry project that indexes a large internal help-desk knowledge base into Azure AI Search. To improve recall, you want to tag each article with the handful of concepts it is
- You are building a Microsoft Foundry pipeline that must remove customer names, phone numbers, and email addresses from support transcripts before they are archived, replacing each with a masked placeh
- Custom NER needs a labeled authoring project, a training run, and a deployment before it can be called
Custom named entity recognition adds domain-specific entity types beyond the preset list, but only through an authoring project with human-labeled documents, a training run, and an explicit deployment that exposes a runtime prediction endpoint. Prebuilt entity recognition requires none of that — you call the analyze-text runtime immediately with the entity recognition task kind.
Trap Assuming a new domain entity type can be added by configuration or prompt alone, with no labeled data and no deployment step.
5 questions test this
- Your Microsoft Foundry project must extract two entity types that don't exist in the prebuilt category list, an internal contract 'clause type' and a proprietary 'asset tag' format, from thousands of
- In a Microsoft Foundry project your team created a custom NER authoring project, labeled several hundred documents, ran training, and reviewed strong evaluation metrics for a new 'shipment tracking co
- A developer on your team wants prebuilt Azure Language NER to start returning a new 'policy number' entity that is specific to your insurance product. They tried enabling it through the analyze-text r
- You are building a contracts-processing agent in a Microsoft Foundry project. The agent must extract a company-specific entity type - an internal 'master service agreement clause reference' - that doe
- Your team processes incoming insurance-claim emails in a Microsoft Foundry project and must automatically identify and categorize the people, organizations, locations, and monetary quantities that eac
- The analyze-text runtime can batch several Language tasks over one document collection
A synchronous analyze-text call runs a single task over the submitted documents, while the asynchronous job endpoint accepts several tasks — for example entity recognition, key phrase extraction, and PII detection — over the same document collection in one submission. Batching this way avoids re-sending the corpus once per feature.
Trap Issuing one synchronous call per feature over the same documents and paying the ingestion cost repeatedly.
- Omitting the language code makes Language analysis default to English and silently lose recall
Prebuilt Language tasks accept a per-document language code, and when none is supplied the analysis defaults to English. Supported entity categories also differ by input language, so a non-English document analyzed without its language code returns degraded results with no error, and categories not enabled by default for that language must be requested explicitly.
Trap Treating missing recall on multilingual text as a model-quality issue rather than an unset language code.
- Extractive summarization returns ranked verbatim sentences with offsets; abstractive generates new wording
Extractive summarization selects the highest-ranked original sentences from the source and returns each with a rank score plus its start position and length, so every word in the summary is verbatim and traceable to a location in the input. Abstractive summarization writes new, coherent sentences that appear nowhere in the source and returns a contextual input range rather than sentence offsets.
Trap Choosing abstractive summarization when the requirement is that no wording may be invented and each summary line must map back to a source offset.
6 questions test this
- You are adding an audit view to a Microsoft Foundry compliance tool. For every summary the tool produces, the UI must highlight, inside the original document, the exact spans the summary was built fro
- You are building a Microsoft Foundry app for a compliance team that condenses lengthy regulatory filings into short briefs. Auditors mandate that every sentence in a brief be reproduced word for word
- A litigation-support tool on Microsoft Foundry displays long depositions and must highlight the most important sentences directly inside the original document view, drawing a marker at each sentence's
- A regulatory-reporting team on Microsoft Foundry must condense filed disclosure letters. Compliance forbids introducing any wording that does not appear in the source, and every line of the summary mu
- You are building a Microsoft Foundry executive-briefing feature that turns long technical incident reports into a single, fluent paragraph for leadership. Stakeholders want the paragraph written in sm
- A knowledge-base team on Microsoft Foundry wants short, readable blurbs for long technical articles. The blurbs must read as fresh, fluent prose written in the service's own words rather than being st
- Conversation summarization is requested per aspect and needs turn-structured input
Conversation summarization accepts structured, speaker-tagged conversational input and is requested per aspect: issue and resolution for contact-center calls, recap for a single-paragraph summary, and chapterTitle together with narrative to segment a long conversation and summarize each segment. Text summarization accepts only a plain text block and has no aspect concept at all.
Trap Flattening a call transcript into plain text for text summarization and still expecting separated issue and resolution output.
5 questions test this
- Your Microsoft Foundry solution ingests speaker-tagged transcripts of hour-long financial-advisory calls. For each completed call, compliance wants a single concise one-paragraph overview that capture
- Your Microsoft Foundry review tool processes speaker-tagged transcripts of long compliance review calls, where a single call moves through many distinct topics in one session. Reviewers need each call
- Your contact-center analytics workload on Microsoft Foundry ingests two-party support calls and must emit a separated issue summary and a separated resolution summary for each call. The audio has alre
- Your team operates a Microsoft Foundry contact-center solution and stores chat logs between customers and support agents. Compliance wants each closed case reduced to a clearly separated customer issu
- Your team on Microsoft Foundry summarizes live agent-customer chat sessions into a one-paragraph recap for the CRM. Each session arrives as structured turns tagged with participant and role, and the r
- Summarization retires from Azure Language and Microsoft directs new projects to Foundry models
Microsoft has published a retirement date for Summarization in Azure Language (31 March 2029) and directs both existing workloads and all new projects to Microsoft Foundry models for natural-language understanding. For a green-field Foundry build the task-specific summarization API is a migration path for legacy code, not the recommended default.
Trap Standardizing a brand-new Foundry solution on the prebuilt Language summarization task because it is the 'purpose-built' service.
3 questions test this
- Your organization is starting a brand-new Microsoft Foundry project to generate compliance summaries, and there is no existing code to preserve. A teammate proposes standardizing the entire solution o
- A production Microsoft Foundry application relies heavily on the Azure Language summarization REST task, which was appropriate when the app was first built. Leadership asks you for a multi-year roadma
- You are starting a green-field natural-language-understanding build on Microsoft Foundry that includes document summarization. A colleague argues you should standardize on the prebuilt Summarization t
- Domain summarization that must hit fixed sections or highlight clauses needs a prompted model, not the prebuilt task
Compliance and other domain summarization work carries output requirements the prebuilt task cannot express: mandatory sections, a fixed tone, named clause types to call out, and citations back to the source. A Foundry model steered by a system prompt plus a strict JSON schema delivers that control, while the prebuilt summarization API exposes only summary-length style controls over content it chooses itself.
Trap Assuming a task-optimized summarizer can be configured to always surface a specific clause type; it has no such steering surface.
6 questions test this
- You are building a Microsoft Foundry pipeline that summarizes regulatory filings and writes each result straight into a downstream compliance database. Every summary must arrive as the same machine-pa
- A regulatory-summary microservice on Microsoft Foundry must post each contract summary to a downstream compliance system as JSON with fixed fields, a summary section, a risk rating, and a cited source
- A team already uses the prebuilt abstractive summarization task to summarize contracts. A new compliance rule requires that every summary always surface any indemnification and limitation-of-liability
- A compliance team on Microsoft Foundry must summarize vendor contracts. Every summary has to contain the same mandatory sections, keep a fixed formal tone, always call out termination and indemnificat
- You are building a Microsoft Foundry compliance summarizer for contracts. Each output must always contain the same fixed section headings, maintain a mandatory formal tone, explicitly call out predefi
- A legal-ops team on Microsoft Foundry summarizes NDAs and requires that every summary always surfaces the confidentiality-term clause, under a fixed heading, even when that clause is not among the mos
- Asynchronous Language job output is retrievable for 24 hours and then purged
Summarization is processed as an asynchronous job whose output is available for retrieval for 24 hours from ingestion, after which the results are purged and cannot be fetched again. A production pipeline must persist the returned summaries itself rather than treating the job identifier as durable storage.
Trap Storing only the job identifier and planning to re-read the result days later.
- Sentiment analysis scores positive, neutral, and negative at both document and sentence level
The sentiment task returns confidence scores between 0 and 1 for positive, neutral, and negative for the document as a whole and for each sentence inside it, then assigns the label with the highest score at each level. Because scoring is per sentence as well as per document, a long review whose document label is neutral can still contain individually negative sentences that a document-only reading would miss.
Trap Routing escalations on the document label alone and losing the negative sentences buried inside long feedback.
9 questions test this
- You are building a Foundry solution that analyzes long customer support email threads. For each email you need one overall sentiment verdict for triage, and separately the sentiment of each individual
- Your team analyzes hotel guest reviews in a Foundry pipeline and already gets an overall positive, neutral, or negative label per review from Azure Language sentiment analysis. Product owners now want
- A Foundry solution processes recorded customer-service calls. The team must flag calls where the caller is frustrated or urgent. The built-in Sentiment field only returns positive, neutral, or negativ
- A Foundry review-analytics dashboard calls Azure Language sentiment analysis and buckets each product review by its document-level label. The team expected only positive, neutral, or negative, but som
- Your team analyzes hotel guest reviews in a Foundry solution and must report sentiment for each mentioned aspect — the room, the staff, the breakfast — rather than one verdict per review, so operation
- Your team ships a Foundry app that routes customer reviews to a human agent whenever feedback turns negative. It calls Azure Language sentiment analysis on each review, but long multi-paragraph review
- A Foundry app runs Azure Language sentiment analysis with opinion mining on restaurant reviews. For the sentence 'The pasta was delicious but the service was slow,' a developer expects a single sentim
- Your support-analytics team wants to flag chat transcripts that show customer frustration and escalation risk and route them to a supervisor. A developer proposes using Azure Language sentiment analys
- A voice-of-customer team uses Azure Language sentiment analysis on multi-paragraph survey verbatims collected in a Foundry project. Leadership currently sees only the overall document sentiment, but t
- Opinion mining is aspect-based sentiment that attributes each opinion to a specific target
Opinion mining is an option on the sentiment task, not a separate service, and it performs aspect-based sentiment analysis: it links each expressed sentiment to the concrete target it is about — 'the room', 'the staff', 'battery life' — and returns target and assessment pairs. Base sentiment analysis returns only an overall label per sentence with no attribution to a product or service attribute.
Trap Expecting per-attribute sentiment from the sentiment task without enabling opinion mining.
9 questions test this
- Your team analyzes hotel guest reviews in a Foundry pipeline and already gets an overall positive, neutral, or negative label per review from Azure Language sentiment analysis. Product owners now want
- Your support team wants to flag written customer chats that express specific tones — frustration, urgency, and escalation risk — so at-risk conversations jump the queue. They tried Azure Language sent
- A Foundry solution processes recorded customer-service calls. The team must flag calls where the caller is frustrated or urgent. The built-in Sentiment field only returns positive, neutral, or negativ
- A contact center records customer calls in a Foundry solution and wants to flag calls where the caller is frustrated or on the verge of escalating. Running Azure Language sentiment analysis over the t
- A Foundry review-analytics dashboard calls Azure Language sentiment analysis and buckets each product review by its document-level label. The team expected only positive, neutral, or negative, but som
- Your team analyzes hotel guest reviews in a Foundry solution and must report sentiment for each mentioned aspect — the room, the staff, the breakfast — rather than one verdict per review, so operation
- A retail analytics team wants to know which specific product attributes — battery life, screen, packaging — customers praise or criticize in written reviews, not just whether each review is positive o
- A Foundry app runs Azure Language sentiment analysis with opinion mining on restaurant reviews. For the sentence 'The pasta was delicious but the service was slow,' a developer expects a single sentim
- Your support-analytics team wants to flag chat transcripts that show customer frustration and escalation risk and route them to a supervisor. A developer proposes using Azure Language sentiment analys
- Content Safety text scoring runs on the full 0-7 severity scale and can be trimmed to 0/2/4/6
The Content Safety text model rates Hate, Sexual, Violence, and SelfHarm on the full 0-7 severity scale and can return either that full scale or a trimmed one in which each adjacent pair of levels collapses to a single value (0, 2, 4, 6). Text and multimodal image-with-text scoring offer the eight-level output; classification is multi-label, so one passage can be flagged under more than one category at once.
Trap Building text thresholds on the assumption only four buckets exist, which cannot express the distinction between a level 4 and a level 5 finding.
4 questions test this
- You are building a text-moderation step in a Foundry app with Azure AI Content Safety. Policy requires two different actions: content at a moderate severity gets queued for human review, while clearly
- You are moderating user posts in a Foundry community app. Some posts are simultaneously hateful and sexual, and your policy applies a different action per category, so you need a severity for every ha
- A Foundry moderation service sends user posts to the Azure AI Content Safety Analyze Text API and stores one harm category per post by keeping only the category with the highest severity. A reviewer n
- You configure Azure AI Content Safety text moderation for a community forum. Compliance wants moderators to treat a mid-level violent post differently from a clearly severe one, so your policy must be
- The PII task returns both the detected entity list and a ready-made redacted copy of the text
PII detection evaluates unstructured text for predefined personal and health information categories and returns two things in one response: the entity list with category, offset, length, and confidence, plus a redactedText string in which each detected span is already masked. Called synchronously the feature is stateless — no input is stored in the resource — so a pipeline can log entity metadata and forward only the redacted copy downstream.
Trap Running generic entity recognition and hand-assembling the masked string, which discards the category-aware spans PII detection already produced.
5 questions test this
- You are building a Foundry data pipeline that ingests free-text support tickets. For compliance, you must record which categories of personal information each ticket contained, and you must forward a
- A developer redacts personal data from transcripts by running Azure Language prebuilt named entity recognition, then writing code that blanks out each returned span. The privacy team complains that th
- A healthcare Foundry app must strip patient identifiers from free-text chat messages before they are logged. A privacy requirement states that the message content must not be retained anywhere in the
- You are building a Foundry ingestion pipeline that logs support tickets. Compliance requires two outputs from each ticket: a structured list of the personal data found, with its category and location,
- Your team must minimize where raw customer PII lives, and a data-protection review is under way. A Foundry pipeline sends free-text chat messages to Azure Language PII detection, logs only entity meta
- PII redaction policy kinds differ in whether offsets and length survive masking
Redaction behavior is chosen with a redaction policy kind: characterMask (the default) replaces the span with a repeated character and preserves the original length and offsets, entityMask substitutes a typed placeholder such as [PERSON_1], noMask returns the response without a redactedText field at all, and syntheticReplacement swaps in realistic but fictitious values. Only length-preserving masking keeps downstream character offsets valid.
Trap Selecting entityMask in a pipeline whose later stages index by character offset into the original document.
- Prebuilt sentiment analysis emits only positive, neutral, and negative, so tone categories such as frustration or escalation risk require a generative classification you define
The Language sentiment analysis feature assigns the labels positive, neutral, and negative with confidence scores at both document and sentence level, plus a derived mixed label at document level when a document contains both positive and negative sentences, and opinion mining only adds the target an opinion is attached to; none of these labels has any vocabulary for tone or emotion classes such as frustration, urgency, politeness, sarcasm, or escalation risk. Detecting those means defining the taxonomy yourself - a chat model prompted to classify into a constrained enum with a structured output schema, an evaluator or LLM-judge rubric applied to conversations, or a Content Understanding audio analyzer with custom generative fields when the tone is carried by spoken delivery rather than wording.
Trap Equating a strongly negative sentiment score with a specific tone: 'negative' cannot distinguish an angry customer from a disappointed one, or flag an urgent-but-polite escalation, because it is one axis with three labels. Enabling opinion mining does not add emotion labels either — it is aspect-based sentiment returning target and assessment pairs on the same three-label scale — and neither does lowering a confidence threshold.
4 questions test this
- Your support team wants to flag written customer chats that express specific tones — frustration, urgency, and escalation risk — so at-risk conversations jump the queue. They tried Azure Language sent
- A Foundry solution processes recorded customer-service calls. The team must flag calls where the caller is frustrated or urgent. The built-in Sentiment field only returns positive, neutral, or negativ
- A contact center records customer calls in a Foundry solution and wants to flag calls where the caller is frustrated or on the verge of escalating. Running Azure Language sentiment analysis over the t
- Your support-analytics team wants to flag chat transcripts that show customer frustration and escalation risk and route them to a supervisor. A developer proposes using Azure Language sentiment analys
- A Custom Translator system is selected by category ID, and allowFallback decides whether a miss is silent
A trained Custom Translator system is invoked by passing its category ID in the category query parameter of the translate call. allowFallback defaults to true, letting the request quietly fall back to the general system when no custom system exists for that language pair; setting allowFallback=false makes the request return HTTP 400 instead of a non-custom translation, which is how you prove every returned string used the trained terminology.
Trap Leaving allowFallback at its default in a regulated workflow and assuming every translation applied the custom glossary.
7 questions test this
- A regulated pipeline translates English into both German and French and sets your Custom Translator category ID on every request. You trained and published a custom system for English-to-German only.
- You trained and deployed a Custom Translator system for English-to-Japanese legal terminology and confirmed it is available. Your application still calls Azure Translator's text translate endpoint, bu
- Your team runs a regulated medical-device localization pipeline on Azure Translator. Every returned string must be produced by your trained Custom Translator system, and compliance requires proof that
- An auditor reviewing your English-to-Korean pipeline finds that some translated strings do not reflect your trained Custom Translator terminology, even though every call includes the correct Category
- Your team published a Custom Translator system that encodes your manufacturing division's product and part terminology. A developer calls the text translate endpoint and confirms the request succeeds,
- A legal-services company must translate contracts into several languages using an approved terminology set, and its compliance team demands two things: identical, repeatable output for identical input
- You maintain an English-to-German localization pipeline for a pharmaceutical company, and a colleague has already trained and published a Custom Translator system that encodes the approved clinical te
- The dynamic dictionary pins one phrase inline; broad terminology control requires Custom Translator
The dynamic dictionary supplies a known rendering for a single span inline as <mstrans:dictionary translation="...">phrase. It is case-sensitive, requires the from parameter because autodetection is not allowed with it, and is documented as safe only for proper nouns such as person and product names. Systematic terminology and style control belongs in Custom Translator, which learns those choices from in-context training data.
Trap Injecting dynamic-dictionary markup for an entire glossary instead of training a custom system, and losing source-language autodetection in the process.
11 questions test this
- A localization team wants consistent, systematic rendering of several hundred domain terms and a specific house style across every English-to-Japanese translation. An engineer proposes injecting inlin
- You run a high-volume neural machine translation pipeline. Marketing introduces one newly coined campaign name that must render a specific way in every target language starting with tonight's batch, a
- Your English-to-French pipeline uses the general Translator system, and output quality is fine except that one coined product name, wordomatic, is being altered in the French output. You need to pin e
- A regulated pipeline translates English into both German and French and sets your Custom Translator category ID on every request. You trained and published a custom system for English-to-German only.
- Your team must enforce roughly 600 approved industry term translations and a consistent house style across all English-to-French output from Azure Translator, and the correct choices depend on surroun
- You maintain an English-to-German product-catalog translation flow on Azure Translator's text API. The product name 'SmartBrew' must always appear in German output as the approved localized form 'Smar
- A localization engineer uses Azure Translator's dynamic dictionary to force the product term 'FlexPay' to a fixed German rendering, and it works. Marketing copy, however, sometimes writes the term as
- A legal-services company must translate contracts into several languages using an approved terminology set, and its compliance team demands two things: identical, repeatable output for identical input
- Your English-to-Spanish requests previously relied on automatic source-language detection and worked well. After a developer adds inline dynamic-dictionary markup to pin a brand name in the output, th
- A multilingual support flow on Azure Translator's text API relies on automatic source-language detection because inbound messages arrive in several languages. To keep a specific product name rendered
- You maintain an English-to-German localization pipeline for a pharmaceutical company, and a colleague has already trained and published a Custom Translator system that encodes the approved clinical te
- Translator passes profanity through by default; Marked versus Deleted decides whether the signal survives
By default (profanityAction=NoAction) Translator carries profanity from source to target. Deleted removes the profane words from the output with no replacement, while Marked replaces them — with asterisks by default, or wrapped in tags when profanityMarker=Tag, which leaves the workflow able to detect and post-process the occurrence.
Trap Choosing Deleted in a moderation workflow that still needs to know profanity was present in the source.
- textType=html preserves markup, and class=notranslate excludes an element from translation
Setting textType=html tells Translator the payload is well-formed markup so tags are preserved instead of being translated as prose, and any element carrying class="notranslate" is returned in its source language. That combination is how boilerplate, code samples, brand names, and legal identifiers are excluded from a translated page.
Trap Submitting HTML with the default plain text type, which translates the markup itself and corrupts the document.
- Translating a library of files uses Translator's asynchronous batch document translation over Blob Storage, not a loop over the text endpoint
Azure Translator document translation has two processes: asynchronous batch, which handles multiple and large documents through an Azure Blob Storage account with separate source and target containers authorized by SAS token or managed identity, while you poll job and per-document status; and synchronous single-file, which accepts one document, needs no storage account, and returns the translated file directly in the response. Both preserve the original layout and formatting and can apply a custom translation model and a glossary, but only the batch path accepts PDFs, where OCR extracts and translates the text of a scanned PDF while retaining the original layout - the synchronous path is limited to .txt, .tsv, .csv, .html, .mhtml, .docx, .pptx, .xlsx, .msg, and .xlf. The text translation API is a different surface entirely - it takes and returns strings, so it cannot round-trip a .docx or .pptx.
Trap Extracting text from each file and looping it through the text /translate endpoint, which discards exactly the layout and formatting document translation exists to preserve. The other inversion is picking the synchronous path for a whole library: synchronous accepts only a single document per request, and it is the asynchronous batch mode - not the synchronous one - that requires the blob source and target containers.
4 questions test this
- A Foundry-based contract tool lets a user upload one .docx agreement in the browser and immediately download a French version that keeps the original formatting. The design must avoid provisioning any
- A records team must translate a library of thousands of scanned PDF invoices held in Azure Blob Storage into English, preserving each invoice's original layout in the output. A colleague suggests the
- You are adding an interactive feature to a web app where a user uploads a single Word (.docx) contract and immediately downloads the translated .docx from the response. You want to avoid standing up a
- Your Foundry solution must translate a library of about 4,000 Word and PowerPoint files from a source Azure Blob Storage container into three languages, writing the results to a target container while
References
- What is Azure AI Language
- How to use structured outputs with Azure OpenAI in Microsoft Foundry
- What is Azure AI Translator text translation
- Named entity recognition (NER) overview
- Entity linking overview
- Key phrase extraction overview
- Custom named entity recognition (custom NER) overview
- Use Azure AI Language features asynchronously
- Detect and redact PII from text
- PII detection entity categories
- Sentiment analysis and opinion mining overview
- Azure AI Content Safety harm categories and severity levels
- What is summarization?
- How to use summarization
- Translator v3 Translate method reference
- What is Azure Translator document translation?
- Text translation customization (Custom Translator)
- Use the Translator dynamic dictionary
- Prevent content translation with Translator