Integration overview

Target Audience

The RAI platform is designed to support two primary user role groups. Your role is extremely important in deciding your integration approach. If you are part of the AOAI Customer Team, we recommend following the Green Pathway. If you are part of the AOAI Service Team, you may follow the Purple Pathway.

Please note that this is RAI team’s recommendation, the final integration approach may ultimately depend on your specific scenarios.

AOAI Customer Team

Teams that use AOAI services to develop AI services or Copilot solutions for end-users.

AOAI Service Teams

This includes internal partners within the AOAI organization, such as teams developing CMP, DALL·E, GPT-V, RealtimeAPI, and AgentAPI services.

The RAI Platform Integration Options

To integrate with the RAI platform, you need to decide on two key actions:

1. Provisioning Azure AI Content Safety(AACS) Resources

You will need to decide how AACS resources will be provisioned. Below is a comparison of the two available options:

	Managed Regional Endpoint	Standard Azure Resource Creation
Option Detail	Azure RAI team provision and manage AACS resources. RAI policies also managed by RAI team. Customer need to wait RAI team response on resource provision and policy management.	Customer provision and manage AACS resource. RAI policies also managed by customers. Full control at customer hand.
Ease of Management	High – Centralized management by RAI team	Moderate – Standard Azure resource provision.
Policy Customization	Medium – Shared, centralized policies. Custoner can leverage DEV environment to test policy before request to add a production one.	High – Tailored policies per resource
Flexibility	Medium – Only go to production need RAI team sign off.	High – Adaptable to diverse use cases
Compliance Assurance	High – Uniform and consistent	High – Customizable to specific needs

The below provides a step-by-step guide for integrating with the RAI platform.

AOAI Customer Team

For standardized Azure Resource creation process, follow this guidance to provision AACS resources by yourself:

• Provision AACS resources

AOAI Service Teams

If you need Azure RAI team to provision AACS resources for you, please contact Harper Zhang (zhanxia@microsoft.com) or Bowen Gong (bowgong@microsoft.com).

2. Integration Methods

After provisioning, your team will need to update your applications to call AACS API. This differs based on the protocol you choose:

HTTP : A widely-used protocol suitable for standard API-based integrations.

HTTP Protocol: Update your API payloads to align with the HTTP API schema.

GRPC : A high-performance, low-latency protocol designed for streaming and real-time processing.

gRPC Protocol: For the gRPC protocol, the RAI platform supports two schemas. Choose the one that best fits your team’s use case:

• Standard mode A general-purpose schema.
• AOAI alignment mode This schema aligns the payload with the AOAI format, reducing effort for AOAI teams in payload parsing.

Compare RAIO and AACS API

Below section compares the request & response of RAIO and AACS API with AOAI default policy 189. This section aims to give you an overview of what will be changed with a simple sample. Please refer to API reference in previsou section for more details.

HTTP

AACS Request and response

Request

POST https://acs-ppe-weu-mapping-usc-f0.ppe.cognitiveservices.azure.com/contentsafety/analyzeWithRaiPolicy?api-version=2024-12-15-preview

Header: N/A

Body

{
  "raiPolicyName": "189", // replace by your legacy policy
  "messages":[
    {
      "role": "User",
      "source": "Prompt",
      "contents": [
        {
          "kind": "Text",
          "text": "I hate u and I will kill u"
        }
      ]
    } 
  ]
}

Response

{
  "taskResults": [
    {
      "settingId": "JailbreakBlocklist_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": false,
      "kind": "Blocklist",
      "blocklistTaskResult": {
        "name": "JailbreakBlockList",
        "isDetected": false,
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "isDetected": false,
            "isBlockingCriteriaMet": false,
            "details": {}
          }
        ]
      }
    },
    {
      "settingId": "Hate_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": false,
      "kind": "HarmCategory",
      "harmCategoryTaskResult": {
        "harmCategory": "Hate",
        "severity": 2,
        "riskLevel": "Low",
        "harmCategoryDetails": {},
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "severity": 2,
            "riskLevel": "Low",
            "isBlockingCriteriaMet": false,
            "details": {}
          }
        ]
      }
    },
    {
      "settingId": "Sexual_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": false,
      "kind": "HarmCategory",
      "harmCategoryTaskResult": {
        "harmCategory": "Sexual",
        "severity": 0,
        "riskLevel": "Safe",
        "harmCategoryDetails": {},
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "severity": 0,
            "riskLevel": "Safe",
            "isBlockingCriteriaMet": false,
            "details": {}
          }
        ]
      }
    },
    {
      "settingId": "Violence_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": true,
      "kind": "HarmCategory",
      "harmCategoryTaskResult": {
        "harmCategory": "Violence",
        "severity": 5,
        "riskLevel": "Medium",
        "harmCategoryDetails": {},
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "severity": 5,
            "riskLevel": "Medium",
            "isBlockingCriteriaMet": true,
            "details": {}
          }
        ]
      }
    },
    {
      "settingId": "SelfHarm_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": false,
      "kind": "HarmCategory",
      "harmCategoryTaskResult": {
        "harmCategory": "SelfHarm",
        "severity": 0,
        "riskLevel": "Safe",
        "harmCategoryDetails": {},
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "severity": 0,
            "riskLevel": "Safe",
            "isBlockingCriteriaMet": false,
            "details": {}
          }
        ]
      }
    },
    {
      "settingId": "PromptInjection_Prompt",
      "resultCode": "Ok",
      "resultCodeDetail": "",
      "isBlockingCriteriaMet": false,
      "kind": "HarmCategory",
      "harmCategoryTaskResult": {
        "harmCategory": "PromptInjection",
        "isDetected": false,
        "harmCategoryDetails": {
          "PromptInjection": false,
          "CrossDomain": false
        },
        "contentResultDetails": [
          {
            "messageIndex": 0,
            "contentIndex": 0,
            "isDetected": false,
            "isBlockingCriteriaMet": false,
            "details": {
              "PromptInjection": false,
              "CrossDomain": false
            }
          }
        ]
      }
    }
  ]
}

RAIO request and response

Request

POST https://rai-orchestrator-prod.eastus.inference.ml.azure.com/annotate

Headers:

• Policy-Id: 189
• Text-Type: MODEL_GENERATED

Body:

{
  "text": [
    "I hate u and I will kill u"   
  ]
}

Resonse

[
  {
    "HateSpeechPattern": false,
    "IPCodeCitations": [],
    "IPNLCitations": [],
    "MultiSeverity_HateSpeech": {
      "0": 1,
      "1": 0.94024336,
      "2": 0.9309621,
      "3": 0.074365705,
      "4": 0.053107902,
      "5": 0.03204008,
      "6": 0.03204008,
      "7": 0.00007311254
    },
    "MultiSeverity_HateSpeechDangerous": 0.00007311254,
    "MultiSeverity_HateSpeechExplicit": 0.03204008,
    "MultiSeverity_HateSpeechLow": 0.94024336,
    "MultiSeverity_HateSpeechMature": 0.03204008,
    "MultiSeverity_HateSpeechNotable": 0.9309621,
    "MultiSeverity_HateSpeechOvert": 0.053107902,
    "MultiSeverity_HateSpeechQuestionable": 0.074365705,
    "MultiSeverity_HateSpeechScore": 2,
    "MultiSeverity_SelfHarm": {
      "0": 1,
      "1": 0.085403666,
      "2": 0.085403666,
      "3": 0.085403666,
      "4": 0.052230857,
      "5": 0.0012594986,
      "6": 0.0004029052,
      "7": 9.2763645e-7
    },
    "MultiSeverity_SelfHarmDangerous": 9.2763645e-7,
    "MultiSeverity_SelfHarmExplicit": 0.0004029052,
    "MultiSeverity_SelfHarmLow": 0.085403666,
    "MultiSeverity_SelfHarmMature": 0.0012594986,
    "MultiSeverity_SelfHarmNotable": 0.085403666,
    "MultiSeverity_SelfHarmOvert": 0.052230857,
    "MultiSeverity_SelfHarmQuestionable": 0.085403666,
    "MultiSeverity_SelfHarmScore": 0,
    "MultiSeverity_Sexual": {
      "0": 1,
      "1": 0.0043823365,
      "2": 0.0017073674,
      "3": 0.0004691764,
      "4": 0.0003077431,
      "5": 0.00020342697,
      "6": 0.00014202365,
      "7": 0.000019223171
    },
    "MultiSeverity_SexualDangerous": 0.000019223171,
    "MultiSeverity_SexualExplicit": 0.00014202365,
    "MultiSeverity_SexualLow": 0.0043823365,
    "MultiSeverity_SexualMature": 0.00020342697,
    "MultiSeverity_SexualNotable": 0.0017073674,
    "MultiSeverity_SexualOvert": 0.0003077431,
    "MultiSeverity_SexualQuestionable": 0.0004691764,
    "MultiSeverity_SexualScore": 0,
    "MultiSeverity_Violence": {
      "0": 1,
      "1": 0.9993255,
      "2": 0.9993255,
      "3": 0.9976859,
      "4": 0.9784671,
      "5": 0.89858866,
      "6": 0.003260346,
      "7": 0.0002959571
    },
    "MultiSeverity_ViolenceDangerous": 0.0002959571,
    "MultiSeverity_ViolenceExplicit": 0.003260346,
    "MultiSeverity_ViolenceLow": 0.9993255,
    "MultiSeverity_ViolenceMature": 0.89858866,
    "MultiSeverity_ViolenceNotable": 0.9993255,
    "MultiSeverity_ViolenceOvert": 0.9784671,
    "MultiSeverity_ViolenceQuestionable": 0.9976859,
    "MultiSeverity_ViolenceScore": 5,
    "SexualPattern": false
  }
]

gRPC example - work in progress

Contact Harper Zhang (zhanxia@microsoft.com) and Bowen Gong (bowgong@microsoft.com) if you have any questions.