建立一個分析文字的客戶端應用程式

客戶端應用程式是您撰寫的程式，連接服務或模型並利用其功能。 你的程式碼會自動向服務發送請求並接收結果——使得處理大量文字或將 AI 分析整合進工作流程成為可能。

要連接 AI 服務，你的應用程式會使用 API （應用程式介面）。 API 是一組規則，定義兩個軟體如何溝通。 用戶端函式庫是一組現成的程式碼，開發者可以在應用程式中使用，方便地與服務或 API 溝通。 你可以在以下內容中複習應用和端點的基礎內容：Azure 的 AI 入門。

使用通用 AI 模型進行文本分析

先從 Microsoft Foundry 資源開始，並在資源中建立一個 Foundry 專案。 在 新的 Foundry 入口網站中，您可以瀏覽模型目錄並部署通用模型。

你可以用 Azure OpenAI API 建立一個客戶端應用程式，與 Microsoft Foundry 模型互動。 OpenAI API 讓你的程式碼能透過向 端點發送請求，與已部署的模型對話，並附上 API 金鑰 以證明你已授權。

在 Azure OpenAI 中，Responses API 是現代的統一 API，用於與語言模型互動。 它設計用來處理完整的 AI 互動，而不僅僅是文字生成。

你可以使用 Responses API 將自然語言提示傳送給已部署的語言模型。 當你需要靈活、對話式的分析，不需要固定的結構化輸出時，它很有用。

使用 OpenAI Python 函式庫

OpenAI Python函式庫 是一個官方的 Python 軟體開發套件（SDK），讓開發者能夠透過程式碼而非原始 HTTP 請求，建立與 OpenAI 模型和服務互動的Python應用程式。

要使用 OpenAI Python 函式庫，你需要在程式碼編輯器中操作。 應用程式程式碼以 code editors 撰寫，例如 Visual Studio Code。 程式碼編輯器的 終端機 是編輯器內建的命令列視窗，你可以在不離開開發環境的情況下執行指令。

1. 安裝必要的套件

OpenAI Python函式庫可透過以下方式安裝於 Visual Studio Code terminal

pip install openai

2. 建立設定檔

接著，你可以建立一個設定檔（型別 .env）來儲存環境變數，例如端點、鍵和模型部署名稱。

請考慮以下變數：

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/openai/v1/
MODEL_DEPLOYMENT_NAME=gpt-4.1-mini
API_KEY=<your-foundry-key>

注意端點變數包含你的 Foundry 資源名稱和 openai.azure.com/openai/v1。 你的 API 金鑰就是你的 Foundry 專案金鑰。

模型部署名稱是 你在 部署模型時給它的名字。 例如，當你部署 gpt-4.1 模型時，你可以將其命名為 gpt-demo-model。 部署名稱為 gpt-demo-model。 然而，如果你不自訂型號名稱，部署名稱會與型號名稱相符，就像上面那段摘要所示。

3. 建立包含應用程式邏輯的檔案

請參考以下應用程式碼範例：

import os
from dotenv import load_dotenv
from openai import OpenAI

# Load environment variables from .env file
load_dotenv()
endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
api_key = os.getenv("API_KEY")
deployment_name = os.getenv("MODEL_DEPLOYMENT_NAME")

# Create the client object
client = OpenAI(
    base_url=endpoint,
    api_key=api_key
)

# Make a request using the client
message = client.responses.create(
    model=deployment_name,
    input="",
)

# Print the results
print(f"Sentiment: {message.output[0]}")

我們使用 Foundry 資源端點與金鑰來建立一個認證的 客戶端物件。 這個 OpenAI 類別由 SDK 定義，並作為連接 OpenAI API 的藍圖。 Python 中的認證客戶端物件是一個服務專用物件，可以安全地進行授權的 API 呼叫，無需程式碼手動管理權杖或秘密。

一旦你建立了一個客戶 端物件 ——已經設定好端點和金鑰——你就可以呼叫它上 的方法 來與模型互動。 例如，你可以用這個 responses方法 將提示符傳送到特定的模型部署。

我們可以透過在終端機中執行應用程式代碼，並用指令 python <file_name>.py來顯示分析結果。

OpenAI API 使用簡單，但因模型以機率方式產生文字，結果可能因呼叫而異。 實務上，這表示兩個相同提示的通話可能會回傳略有不同的措辭或格式。 當你的應用程式需要一致且結構化的數值，例如語言代碼、信心分數或經過遮蔽的文字時，Azure 語言 SDK 是更好的選擇。

使用 Azure 語言 SDK

Azure 語言 SDK 是一個用於 Azure 語言 的用戶端函式庫，這是 Foundry Tools 中的一部分。 SDK 讓開發者能輕鬆地將自然語言處理功能，例如語言偵測和隱藏個人識別資訊（PII），整合到他們的應用程式中。

讓我們來看看你如何使用 Azure 語言 Python SDK 來建立一個分析文字的應用程式。 要使用 Azure 語言 Python SDK，你需要有 Foundry 資源。 接著你需要安裝相容的 Python 版本和 Azure 語言的 Python SDK。

Python SDK 可透過以下方式安裝於 Visual Studio Code terminal

pip install azure-ai-textanalytics

請參考以下設定檔範例：

AZURE_LANGUAGE_ENDPOINT=https://<your-resource>.cognitiveservices.azure.com/
API_KEY=<your-foundry-key>

請參考以下應用程式程式碼範例：

# Import packages
import os
from dotenv import load_dotenv
from azure.core.credentials import AzureKeyCredential
from azure.ai.textanalytics import TextAnalyticsClient

# Load environment variables from .env file
load_dotenv()
endpoint = os.getenv("AZURE_LANGUAGE_ENDPOINT")
key = os.getenv("API_KEY")

# Create the client
client = TextAnalyticsClient(endpoint=endpoint, credential=AzureKeyCredential(key))

# Make a request using the client for language detection
text = "¡Hola! Me llamo Josefina y vivo en Madrid, España."
result = client.detect_language([text])[0]

我們使用客戶端的 methods來呼叫 Azure 語言函式，例如 detect_language 和 recognize_pii_entities。

語言偵測：此 detect_language() 方法會根據文字字串清單回傳偵測到的語言、其 ISO 639-1 代碼，以及介於 0 到 1 之間的信心分數。

text = "¡Hola! Me llamo Josefina y vivo en Madrid, España."
result = client.detect_language([text])[0]

# Print the results
print(f"Language      : {result.primary_language.name}")
print(f"ISO code      : {result.primary_language.iso6391_name}")
print(f"Confidence    : {result.primary_language.confidence_score:.2f}")

PII 偵測：該 recognize_pii_entities() 方法識別文字中的個人細節，並回傳經過遮蔽的文字版本及所發現實體的清單，包括每個實體的類別與信心分數。

text = "Maria Garcia called from 020 7946 0958 and asked to send documents to 42 Market Road, London, UK, SW1A 1AA."

result = client.recognize_pii_entities([text])[0]

# Print the results
print("Redacted text:", result.redacted_text)
print("\nEntities found:")
for entity in result.entities:
    print(f"  {entity.text} | category={entity.category} | confidence={entity.confidence_score}")

透過 OpenAI API 和 Azure 語言 SDK，你可以為處理自然語言並從文字中產生洞見的 AI 應用程式撰寫程式碼。

接著，讓我們看看如何在 AI 代理中納入 Azure 語言功能。