AI-103: Text Analysis, PII, Content Safety and Translation with Foundry

Use prebuilt named entity recognition (NER) in Azure Language when the entities are standard types, custom NER when they are your own categories and you need offsets and a retrainable model, and a prompted language model with a strict schema when the categories are your own but you have no labelled data and need only the values. Prebuilt and custom NER are both core Azure Language features, which Microsoft recommends for new development.

Two near-misses come up often. Custom text classification labels a whole document; it doesn't find mentions inside the text. Key phrase extraction returns the main phrases of the text with no categories and can't be trained on your labels. Neither is an entity extractor.

The deciding facts are usually three: are the categories standard or your own, does labelled data exist, and does a downstream system need exact character offsets? Generated JSON from a language model gives values, not dependable span positions, and a few-shot prompt is not a model a data team can retrain.

Use structured outputs: send a JSON schema with the request (in the Responses API, text.format with type set to json_schema and strict set to true) so decoding is constrained to the schema. Instructions in a prompt ask for a shape; a strict schema guarantees it.

Strict mode has rules that a schema must follow, or the request fails with a schema validation error:

• Every property is listed in required, on every object, nested objects included. Removing a field from required does not make it optional; it makes the schema invalid.
• additionalProperties is false on every object, including nested ones.
• Optional values are null unions. Declare a field that may be absent as {"type": ["string", "null"]} and tell the model to return null when the document doesn't state it. Without a null option, the model has no valid way to say "missing" and tends to invent a plausible value.

schema = {
    "type": "object",
    "properties": {
        "invoice_number": {"type": "string"},
        "due_date": {"type": ["string", "null"]},
        "currency": {"type": "string", "enum": ["USD", "EUR", "GBP"]},
    },
    "required": ["invoice_number", "due_date", "currency"],
    "additionalProperties": False,
}

Match the fix to the failure:

Lowering temperature makes output more repeatable but never restricts it to allowed values; raising temperature adds randomness and makes consistency worse. Turning strict off makes an invalid schema accepted but gives up the adherence guarantee.

Split it, summarize each part, then combine the partial summaries: a map-reduce pattern. A model can only read what fits in its context window, so every part of the document must go through some request if the summary has to cover all of it.

1. Map: split on natural boundaries (sections, agenda items, chapters) so each chunk fits the window. Keep each chunk's reference (section number, paragraph) with its summary so points stay traceable.
2. Reduce: combine the chunk summaries into one summary in a final request.
3. Reduce in levels when needed: if all the chunk summaries together overflow the window, combine them in groups, then combine the group summaries. This hierarchical reduce scales with document size, because the number of levels grows with the input while each request stays within the window.

The test for any proposed shortcut is simple: does every part of the input still reach a model request? Anything that discards, samples or skips input, however it is labelled, produces a summary of part of the document. Settings on the output side, such as the output token limit, control how long the response may be and have no effect on how much input fits. A phrase list is not a summary either: key phrase extraction (a legacy Azure Language feature) returns topics, not what was discussed or decided.

Use Azure Language sentiment analysis for an existing app that already calls it; use a language model with a schema for new builds and for labels the service doesn't have, such as tone or sarcasm. Microsoft's Azure Language overview classifies sentiment analysis and opinion mining as legacy capabilities: supported for existing implementations, not recommended for new development.

What the service returns: sentence-level sentiment (positive, negative or neutral) and a document-level label that can also be mixed, each with confidence scores. With the Python TextAnalyticsClient, calling analyze_sentiment(documents, show_opinion_mining=True) adds opinion mining: for each sentence, the targets (aspects such as "battery" or "screen") and the assessments about them, each with its own sentiment. For an existing app that needs per-feature sentiment, that one flag is the smallest change. Changing model_version doesn't add aspects or new label types.

Sentiment is not safety. Azure AI Content Safety rates harm categories; it says nothing about whether a comment is positive or sarcastic.

Call the Content Safety text analysis API (text:analyze) on any text you want to screen: it returns a severity for each harm category (Hate, Sexual, Violence, SelfHarm) and can check custom blocklists in the same call. It works on arbitrary text, with no language model in the path.

• categories limits which harm categories are analyzed. It doesn't change the severity scale.
• outputType: FourSeverityLevels (the default) returns 0, 2, 4 or 6; EightSeverityLevels returns 0 to 7. A policy that separates severity 4 from 5 needs the eight-level scale. On the default scale, low is 2, medium is 4 and high is 6.
• blocklistNames names custom text blocklists to check, for terms the classifiers score as safe but your policy bans: community slang, counterfeit brand names, banned product terms.
• haltOnBlocklistHit: when true, a blocklist match stops further harm analysis for that text (saving latency). It defaults to false, and it does nothing unless a blocklist is named.

{
  "text": "<message>",
  "blocklistNames": ["banned-terms"],
  "outputType": "FourSeverityLevels"
}

Text analysis or model guardrails?

Guardrails (content filters) on a Foundry model deployment screen the requests and responses of that deployment. If text never goes to a model, such as listings published straight from a web form or a nightly export job, a guardrail never sees it. Calling Content Safety text analysis directly is cheaper and simpler than routing the text through a chatbot deployment just to trigger its guardrails. Configuring deployment guardrails, Prompt Shields and protected material detection is covered in the responsible AI lesson; note here only that Prompt Shields detects prompt injection and jailbreak attempts, not hate or sexual content.

Use Azure Language PII detection, a core feature: it finds sensitive categories such as Person, PhoneNumber, Address, CreditCardNumber and US Social Security numbers, and returns redacted text alongside a list of entities, each with its category, offset, length and confidence score.

responses = text_client.recognize_pii_entities(
    support_tickets,
    categories_filter=[
        PiiEntityCategory.PHONE_NUMBER,
        PiiEntityCategory.EMAIL,
    ],
)
for ticket in responses:
    print(ticket.redacted_text)
    for entity in ticket.entities:
        print(entity.category, entity.confidence_score)

• By default every supported category for the language is detected and masked, so names, addresses and organizations disappear too. categories_filter (piiCategories in REST) restricts detection, and therefore redaction, to the categories you list.
• domain_filter set to protected health information (phi) adds health-domain entities. It doesn't narrow results to specific categories.
• Filtering the returned entity list after the call doesn't change redacted_text, which the service already masked for every detected category.
• disable_service_logs controls whether the service logs input for troubleshooting; it doesn't change detection.
• Confidence scores per entity let you route low-confidence detections to a human reviewer, something a prompted rewrite ("replace identifiers with [REDACTED]") can't give you.

In Azure Translator API version 2026-06-06 (GA, not backward compatible with v3), each entry in a request's targets array names a language and, optionally, the system that translates it through deploymentName:

Having a GPT deployment or a custom model available changes nothing on its own: a target that sets only a language code goes to general.

Target parameters to know

• tone (formal, informal, neutral) and gender (female, male, neutral) apply to LLM-based translation only. Requesting a formal register therefore needs both an LLM deploymentName and the parameter.
• allowFallback defaults to true: if the named model doesn't support the language pair, the service quietly uses the general system. Set it to false when only LLM output is acceptable, so the request fails instead.
• textType defaults to plain; set html when the input contains markup so elements are preserved. Text marked as not to be translated stays as it is.
• Settings such as script (writing system) and profanity handling don't affect markup, tone or fallback.

Private endpoints

Microsoft documents that LLM-based translation isn't available when the Translator resource uses a private endpoint. NMT keeps working privately but has no tone control, and tone is an LLM-only parameter. Register control on private networking therefore can't come from Translator itself; it comes from instructions to a language model whose deployment is itself reachable privately (next sections).

What was removed

Version 2026-06-06 dropped the v3 Detect, BreakSentence and Dictionary methods. To identify a text's language without translating it, Microsoft points to Azure Language language detection, a core Azure Language feature. Leaving out the source language in a translate call does return a detected language, but only as part of a paid translation.

Translating documents with their formatting

Translator document translation keeps a file's structure and layout. It has two modes:

Translating extracted text as plain text loses the document's layout, and transliteration converts between scripts (for example into Latin script) without translating anything. For HTML strings sent to text translation, set textType to html rather than using document translation.

Pick the adaptation by the system you're allowed to use and how much data you have: adaptive custom translation and reference text pairs steer LLM translation without training; a Custom Translator model is a trained NMT model.

• Precedence: the two LLM adaptation inputs aren't combined. When referenceTextPairs is supplied, adaptiveDatasetId is ignored. To keep a dataset's terminology and add a new term, add the new pairs to the dataset instead of passing them inline.
• Volume and lead time: inline reference pairs are capped per target, so a large glossary belongs in an adaptive dataset, which is indexed rather than trained and is usable quickly. A Custom Translator model needs a training run.
• Which system is allowed: adaptive datasets, reference pairs and fine-tuned GPT models all steer a language model. Custom Translator is the only adaptation that stays on NMT.
• Neither adaptation adds language support: an unsupported pair still falls back to NMT unless allowFallback is false.

Build an LLM-powered flow, a Foundry model prompted to translate, when the requirement is something Translator's fixed parameters can't express; use Translator NMT when volume and cost dominate. Translator exposes settings (target languages, tone, gender, text type, adaptation), not free-form instructions.

Translator can handle parts of these jobs: several targets in one request, text marked as not to be translated. The deciding requirement is usually the one Translator can't express. Prompted translation adds token cost at scale, so don't use it where NMT already meets the need.

Start with system instructions and a few examples, enforce structure with a strict schema, and reach for supervised fine-tuning only when long few-shot prompts are needed on every call to keep a house style. Each layer fixes a different problem.

• Inconsistent format or invented categories mean the model hasn't been told what to produce. Define the types and the format in the system message and add a couple of worked examples. This is fast and needs no training set.
• Verifiable grounding for compliance work: a citation rule in the instructions (every finding cites the paragraph it comes from) plus a schema with a required source_paragraph field per finding, so a finding without a source can't be returned. A required field is what makes the rule enforceable: guidance in a prompt shapes output but can't reject a finding that lacks a source, and any tool that brings in outside content works against grounding in the supplied document.
• A taxonomy that changes (for example quarterly) belongs in a schema enum: decoding is constrained to current values and editing the enum takes effect on the next request. Fine-tuning would bake in old categories and need a new training run per change, and a fine-tuned model can still emit an off-list tag.
• Fine-tuning fits when thousands of approved input and output pairs exist, the knowledge is already in the request, and the cost and latency of sending long examples with every call are the problem. It teaches format, tone and style so the prompt can shrink. The test for alternatives: any approach that still puts the examples into each request keeps their token cost, however the examples are chosen, cached or priced; only moving the behaviour into the model's weights removes them.