Azure AI Innehållsäkerhet klientbibliotek för Python – version 1.0.0

Azure AI Innehållsäkerhet identifierar skadligt användargenererat och AI-genererat innehåll i program och tjänster. Innehållssäkerhet innehåller text- och bild-API:er som gör att du kan identifiera skadligt material:

• API för textanalys: Söker igenom text efter sexuellt innehåll, våld, hat och självskadebeteende med nivåer med flera allvarlighetsgrader.
• API för bildanalys: Söker igenom bilder efter sexuellt innehåll, våld, hat och självskadebeteende med nivåer med flera allvarlighetsgrader.
• API:er för hantering av textblockering: STANDARD-AI-klassificerare är tillräckliga för de flesta innehållssäkerhetsbehov; Du kan dock behöva screena för termer som är specifika för ditt användningsfall. Du kan skapa blocklistor med termer som ska användas med text-API:et.

Dokumentation

Det finns olika dokumentation som hjälper dig att komma igång

• Referensdokumentation för API
• Produktdokumentation

Komma igång

Förutsättningar

• Python 3.7 eller senare krävs för att använda det här paketet.
• Du behöver en Azure-prenumeration för att använda det här paketet.
• En Azure AI Innehållsäkerhet resurs, om det inte finns någon befintlig resurs, kan du skapa en ny.

Installera paketet

pip install azure-ai-contentsafety

Autentisera klienten

Hämta slutpunkten

Du hittar slutpunkten för din Azure AI Innehållsäkerhet-tjänstresurs med hjälp av Azure-portalen eller Azure CLI:

# Get the endpoint for the Azure AI Content Safety service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

Skapa en ContentSafetyClient/BlocklistClient med API-nyckel

Så här använder du en API-nyckel som credential parameter.

• Steg 1: Hämta API-nyckeln. API-nyckeln finns i Azure-portalen eller genom att köra följande Azure CLI-kommando :

  az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  

• Steg 2: Skicka nyckeln som en sträng till en instans av AzureKeyCredential.

  from azure.core.credentials import AzureKeyCredential
  from azure.ai.contentsafety import ContentSafetyClient, BlocklistClient
  
  endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
  credential = AzureKeyCredential("<api_key>")
  content_safety_client = ContentSafetyClient(endpoint, credential)
  blocklist_client = BlocklistClient(endpoint, credential)
  

Skapa en ContentSafetyClient/BlocklistClient med Microsoft Entra ID-tokenautentiseringsuppgifter

• Steg 1: Aktivera Microsoft Entra-ID för resursen. Se det här dokumentet Autentisera med Microsoft Entra-ID för stegen för att aktivera Microsoft Entra-ID för resursen.

  De viktigaste stegen är:

  • Skapa resurs med en anpassad underdomän.
  • Skapa tjänstens huvudnamn och tilldela cognitive services-användarrollen till den.

• Steg 2: Ange värdena för klient-ID, klient-ID och klienthemlighet för Microsoft Entra-programmet som miljövariabler: AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET.

  StandardAzureCredential använder värdena från dessa miljövariabler.

  from azure.identity import DefaultAzureCredential
  from azure.ai.contentsafety import ContentSafetyClient, BlocklistClient
  
  endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
  credential = DefaultAzureCredential()
  content_safety_client = ContentSafetyClient(endpoint, credential)
  blocklist_client = BlocklistClient(endpoint, credential)
  

Viktiga begrepp

Tillgängliga funktioner

Det finns olika typer av analys som är tillgängliga från den här tjänsten. I följande tabell beskrivs för närvarande tillgängliga API:er.

Skadekategorier

Content Safety känner igen fyra olika kategorier av stötande innehåll.

Klassificering kan vara flera etiketter. När ett textexempel till exempel går igenom textmodereringsmodellen kan det klassificeras som både sexuellt innehåll och våld.

Allvarlighetsgrad

Varje skadekategori som tjänsten gäller har också en klassificering på allvarlighetsgrad. Allvarlighetsgraden är avsedd att ange allvarlighetsgraden för konsekvenserna av att visa det flaggade innehållet.

Text: Den aktuella versionen av textmodellen stöder den fullständiga allvarlighetsgradsskalan 0–7. Som standard matar svaret ut 4 värden: 0, 2, 4 och 6. Varje två angränsande nivåer mappas till en enda nivå. Användare kan använda "outputType" i begäran och ange den som "EightSeverityLevels" för att få 8 värden i utdata: 0,1,2,3,4,5,6,7. Du kan läsa definitioner av allvarlighetsgrad för textinnehåll för mer information.

• [0,1] -> 0
• [2,3] -> 2
• [4,5] -> 4
• [6,7] -> 6

Bild: Den aktuella versionen av bildmodellen stöder den trimmade versionen av den fullständiga allvarlighetsgradsskalan 0–7. Klassificeraren returnerar endast allvarlighetsgrad 0, 2, 4 och 6. varje två angränsande nivåer mappas till en enda nivå. Du kan läsa definitioner för allvarlighetsgrad för bildinnehåll för mer information.

• [0,1] -> 0
• [2,3] -> 2
• [4,5] -> 4
• [6,7] -> 6

Hantering av textblockeringslistor

Följande åtgärder stöds för att hantera din textblockeringslista:

• Skapa eller ändra en blockeringslista
• Visa en lista över alla blocklistor
• Hämta en blockeringslista efter blocklistName
• Lägga till blocklistItems i en blocklista
• Ta bort blocklistItems från en blocklista
• Visa en lista över alla blocklistItems i en blocklista efter blocklistName
• Hämta en blocklistItem i en blocklista med blocklistItemId och blocklistName
• Ta bort en blockeringslista och alla dess blocklistItems

Du kan ange de blocklistor som du vill använda när du analyserar text, och sedan kan du få matchningsresultat för blocklista från returnerade svar.

Exempel

I följande avsnitt finns flera kodfragment som täcker några av de vanligaste uppgifterna för innehållssäkerhetstjänsten, inklusive:

• Analysera text
• Analysera bild
• Hantera textblockeringslista

Se exempeldata för de data som används här. Fler exempel finns i exempel.

Analysera text

Analysera text utan blocklistor

    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.ai.contentsafety.models import TextCategory
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    from azure.ai.contentsafety.models import AnalyzeTextOptions

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    # Construct a request
    request = AnalyzeTextOptions(text="You are an idiot")

    # Analyze text
    try:
        response = client.analyze_text(request)
    except HttpResponseError as e:
        print("Analyze text failed.")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

    hate_result = next(item for item in response.categories_analysis if item.category == TextCategory.HATE)
    self_harm_result = next(item for item in response.categories_analysis if item.category == TextCategory.SELF_HARM)
    sexual_result = next(item for item in response.categories_analysis if item.category == TextCategory.SEXUAL)
    violence_result = next(item for item in response.categories_analysis if item.category == TextCategory.VIOLENCE)

    if hate_result:
        print(f"Hate severity: {hate_result.severity}")
    if self_harm_result:
        print(f"SelfHarm severity: {self_harm_result.severity}")
    if sexual_result:
        print(f"Sexual severity: {sexual_result.severity}")
    if violence_result:
        print(f"Violence severity: {violence_result.severity}")

Analysera text med blocklistor

    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import AnalyzeTextOptions
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    input_text = "I h*te you and I want to k*ll you."

    try:
        # After you edit your blocklist, it usually takes effect in 5 minutes, please wait some time before analyzing with blocklist after editing.
        analysis_result = client.analyze_text(
            AnalyzeTextOptions(text=input_text, blocklist_names=[blocklist_name], halt_on_blocklist_hit=False)
        )
        if analysis_result and analysis_result.blocklists_match:
            print("\nBlocklist match results: ")
            for match_result in analysis_result.blocklists_match:
                print(
                    f"BlocklistName: {match_result.blocklist_name}, BlockItemId: {match_result.blocklist_item_id}, "
                    f"BlockItemText: {match_result.blocklist_item_text}"
                )
    except HttpResponseError as e:
        print("\nAnalyze text failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Analysera bild

    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.ai.contentsafety.models import ImageCategory
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]
    image_path = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "./sample_data/image.jpg"))

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    # Build request
    with open(image_path, "rb") as file:
        request = AnalyzeImageOptions(image=ImageData(content=file.read()))

    # Analyze image
    try:
        response = client.analyze_image(request)
    except HttpResponseError as e:
        print("Analyze image failed.")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

    hate_result = next(item for item in response.categories_analysis if item.category == ImageCategory.HATE)
    self_harm_result = next(item for item in response.categories_analysis if item.category == ImageCategory.SELF_HARM)
    sexual_result = next(item for item in response.categories_analysis if item.category == ImageCategory.SEXUAL)
    violence_result = next(item for item in response.categories_analysis if item.category == ImageCategory.VIOLENCE)

    if hate_result:
        print(f"Hate severity: {hate_result.severity}")
    if self_harm_result:
        print(f"SelfHarm severity: {self_harm_result.severity}")
    if sexual_result:
        print(f"Sexual severity: {sexual_result.severity}")
    if violence_result:
        print(f"Violence severity: {violence_result.severity}")

Hantera textblockeringslista

Skapa eller uppdatera textblockeringslista

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.ai.contentsafety.models import TextBlocklist
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    blocklist_description = "Test blocklist management."

    try:
        blocklist = client.create_or_update_text_blocklist(
            blocklist_name=blocklist_name,
            options=TextBlocklist(blocklist_name=blocklist_name, description=blocklist_description),
        )
        if blocklist:
            print("\nBlocklist created or updated: ")
            print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nCreate or update text blocklist failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Lista textblockeringslistor

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    try:
        blocklists = client.list_text_blocklists()
        if blocklists:
            print("\nList blocklists: ")
            for blocklist in blocklists:
                print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nList text blocklists failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Hämta textblockeringslista

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        blocklist = client.get_text_blocklist(blocklist_name=blocklist_name)
        if blocklist:
            print("\nGet blocklist: ")
            print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nGet text blocklist failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Ta bort textblockeringslista

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        client.delete_text_blocklist(blocklist_name=blocklist_name)
        print(f"\nDeleted blocklist: {blocklist_name}")
    except HttpResponseError as e:
        print("\nDelete blocklist failed:")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Lägga till blockItems

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.ai.contentsafety.models import AddOrUpdateTextBlocklistItemsOptions, TextBlocklistItem
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"
    block_item_text_2 = "h*te"

    block_items = [TextBlocklistItem(text=block_item_text_1), TextBlocklistItem(text=block_item_text_2)]
    try:
        result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name, options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=block_items)
        )
        for block_item in result.blocklist_items:
            print(
                f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, Description: {block_item.description}"
            )
    except HttpResponseError as e:
        print("\nAdd block items failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Lista blockItems

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        block_items = client.list_text_blocklist_items(blocklist_name=blocklist_name)
        if block_items:
            print("\nList block items: ")
            for block_item in block_items:
                print(
                    f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, "
                    f"Description: {block_item.description}"
                )
    except HttpResponseError as e:
        print("\nList block items failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Hämta blockItem

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import TextBlocklistItem, AddOrUpdateTextBlocklistItemsOptions
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"

    try:
        # Add a blockItem
        add_result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name,
            options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=[TextBlocklistItem(text=block_item_text_1)]),
        )
        if not add_result or not add_result.blocklist_items or len(add_result.blocklist_items) <= 0:
            raise RuntimeError("BlockItem not created.")
        block_item_id = add_result.blocklist_items[0].blocklist_item_id

        # Get this blockItem by blockItemId
        block_item = client.get_text_blocklist_item(blocklist_name=blocklist_name, blocklist_item_id=block_item_id)
        print("\nGet blockitem: ")
        print(
            f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, Description: {block_item.description}"
        )
    except HttpResponseError as e:
        print("\nGet block item failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Ta bort blockItems

    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import (
        TextBlocklistItem,
        AddOrUpdateTextBlocklistItemsOptions,
        RemoveTextBlocklistItemsOptions,
    )
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"

    try:
        # Add a blockItem
        add_result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name,
            options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=[TextBlocklistItem(text=block_item_text_1)]),
        )
        if not add_result or not add_result.blocklist_items or len(add_result.blocklist_items) <= 0:
            raise RuntimeError("BlockItem not created.")
        block_item_id = add_result.blocklist_items[0].blocklist_item_id

        # Remove this blockItem by blockItemId
        client.remove_blocklist_items(
            blocklist_name=blocklist_name, options=RemoveTextBlocklistItemsOptions(blocklist_item_ids=[block_item_id])
        )
        print(f"\nRemoved blockItem: {add_result.blocklist_items[0].blocklist_item_id}")
    except HttpResponseError as e:
        print("\nRemove block item failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

Felsökning

Allmänt

Azure AI Innehållsäkerhet klientbibliotek skapar undantag som definierats i Azure Core. Felkoder definieras enligt nedan:

Loggning

Det här biblioteket använder standardloggningsbiblioteket för loggning.

Grundläggande information om HTTP-sessioner (URL:er, rubriker osv.) loggas på INFO nivå.

Detaljerad DEBUG nivåloggning, inklusive begärande-/svarskroppar och oredigerade huvuden, kan aktiveras på klienten eller per åtgärd med nyckelordsargumentet logging_enable .

Se fullständig dokumentation om SDK-loggning med exempel här.

Valfri konfiguration

Valfria nyckelordsargument kan skickas på klient- och åtgärdsnivå. Referensdokumentationen för azure-core beskriver tillgängliga konfigurationer för återförsök, loggning, transportprotokoll med mera.

Nästa steg

Ytterligare dokumentation

Mer omfattande dokumentation om Azure Content Safety finns i Azure AI Innehållsäkerhet på docs.microsoft.com.

Bidra

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Du hittar mer information i Vanliga frågor om uppförandekod eller kontakta opencode@microsoft.com för ytterligare frågor eller kommentarer.