Azure OpenAI 连接器 #

概述 #

Azure OpenAI 连接器是 Semantic Kernel 与 Azure OpenAI 服务通信的桥梁，提供企业级的安全性、合规性和可扩展性。

基本配置 #

添加 Azure OpenAI 服务 #

csharp

using Microsoft.SemanticKernel;

var builder = Kernel.CreateBuilder();

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")
);

var kernel = builder.Build();

配置参数说明 #

csharp

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",    // Azure 部署名称
    endpoint: "https://your-resource.openai.azure.com/",  // 终结点
    apiKey: "your-api-key",                // API 密钥
    modelId: "gpt-4",                      // 可选：模型标识
    serviceId: "azure-gpt4"                // 可选：服务标识
);

认证方式 #

API Key 认证 #

csharp

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: configuration["AzureOpenAI:ApiKey"]
);

Azure DefaultAzureCredential #

csharp

using Azure.Identity;

var credential = new DefaultAzureCredential();

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    credentials: credential
);

Managed Identity #

csharp

using Azure.Identity;

// 用于 Azure 资源的托管标识
var credential = new DefaultAzureCredential(
    new DefaultAzureCredentialOptions
    {
        ManagedIdentityClientId = "your-client-id"
    }
);

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    credentials: credential
);

Service Principal #

csharp

using Azure.Identity;

var credential = new ClientSecretCredential(
    tenantId: "your-tenant-id",
    clientId: "your-client-id",
    clientSecret: "your-client-secret"
);

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    credentials: credential
);

部署配置 #

创建 Azure OpenAI 资源 #

text

┌─────────────────────────────────────────────────────────────┐
│                    Azure OpenAI 部署流程                     │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  1. 创建 Azure OpenAI 资源                                   │
│     ┌─────────────────────────────────────────────────┐    │
│     │  az cognitiveservices account create \          │    │
│     │    --name my-openai \                           │    │
│     │    --resource-group my-rg \                     │    │
│     │    --kind OpenAI \                              │    │
│     │    --sku S0                                     │    │
│     └─────────────────────────────────────────────────┘    │
│                                                             │
│  2. 部署模型                                                │
│     ┌─────────────────────────────────────────────────┐    │
│     │  az cognitiveservices account deployment create \│   │
│     │    --name my-openai \                           │    │
│     │    --resource-group my-rg \                     │    │
│     │    --deployment-name gpt-4-deployment \         │    │
│     │    --model-name gpt-4 \                         │    │
│     │    --model-version "latest" \                   │    │
│     │    --sku-capacity 30 \                          │    │
│     │    --sku-name "Standard"                        │    │
│     └─────────────────────────────────────────────────┘    │
│                                                             │
│  3. 获取终结点和密钥                                        │
│     ┌─────────────────────────────────────────────────┐    │
│     │  az cognitiveservices account show \            │    │
│     │    --name my-openai \                           │    │
│     │    --resource-group my-rg \                     │    │
│     │    --query properties.endpoint                  │    │
│     └─────────────────────────────────────────────────┘    │
│                                                             │
└─────────────────────────────────────────────────────────────┘

支持的模型 #

模型	部署名称示例	用途
gpt-4o	gpt-4o-deployment	最新旗舰模型
gpt-4-turbo	gpt-4-turbo-deployment	高性能 GPT-4
gpt-4	gpt-4-deployment	标准 GPT-4
gpt-35-turbo	gpt-35-deployment	快速经济模型
text-embedding-ada-002	embedding-deployment	文本嵌入

执行设置 #

基本配置 #

csharp

using Microsoft.SemanticKernel.Connectors.OpenAI;

var settings = new OpenAIPromptExecutionSettings
{
    MaxTokens = 1000,
    Temperature = 0.7
};

var result = await kernel.InvokePromptAsync(
    "问题",
    new KernelArguments(settings)
);

Azure 特有配置 #

csharp

var settings = new OpenAIPromptExecutionSettings
{
    MaxTokens = 2000,
    Temperature = 0.7,
    TopP = 0.9,
    FrequencyPenalty = 0.5,
    PresencePenalty = 0.5,
    // Azure 特有
    User = "user-identifier",
    Seed = 42
};

嵌入服务 #

配置嵌入服务 #

csharp

builder.AddAzureOpenAITextEmbeddingGeneration(
    deploymentName: "embedding-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: "api-key"
);

使用嵌入服务 #

csharp

var embeddingGenerator = kernel.GetRequiredService<ITextEmbeddingGenerationService>();

var embeddings = await embeddingGenerator.GenerateEmbeddingAsync("文本内容");

Console.WriteLine($"嵌入维度: {embeddings.Length}");

多区域部署 #

配置多区域 #

csharp

var builder = Kernel.CreateBuilder();

// 东亚区域
builder.AddAzureOpenAIChatCompletion(
    serviceId: "azure-eastasia",
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource-eastasia.openai.azure.com/",
    apiKey: "api-key"
);

// 美国区域
builder.AddAzureOpenAIChatCompletion(
    serviceId: "azure-eastus",
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource-eastus.openai.azure.com/",
    apiKey: "api-key"
);

var kernel = builder.Build();

区域故障转移 #

csharp

public class RegionalFailoverService
{
    private readonly Kernel _kernel;
    private readonly string[] _regions = { "azure-eastasia", "azure-eastus" };
    private int _currentRegion = 0;

    public async Task<string> GetCompletionAsync(string prompt)
    {
        var attempts = 0;
        while (attempts < _regions.Length)
        {
            try
            {
                return await _kernel.InvokePromptAsync(
                    prompt,
                    serviceName: _regions[_currentRegion]
                );
            }
            catch (HttpOperationException)
            {
                _currentRegion = (_currentRegion + 1) % _regions.Length;
                attempts++;
            }
        }
        throw new Exception("所有区域都不可用");
    }
}

企业级特性 #

私有终结点 #

csharp

// 使用私有终结点
builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-private-endpoint.privatelink.openai.azure.com/",
    credentials: new DefaultAzureCredential()
);

网络隔离 #

csharp

// 配置 VNet 规则
var handler = new HttpClientHandler
{
    // 配置代理
    Proxy = new WebProxy("http://corporate-proxy:8080"),
    UseProxy = true
};

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: "api-key",
    httpClient: new HttpClient(handler)
);

内容过滤 #

csharp

// Azure OpenAI 自动应用内容过滤
// 可在 Azure 门户配置过滤规则
var result = await kernel.InvokePromptAsync("敏感内容测试");

监控与日志 #

启用诊断日志 #

csharp

using Microsoft.Extensions.Logging;

var loggerFactory = LoggerFactory.Create(builder =>
{
    builder.AddConsole();
    builder.AddApplicationInsights("your-instrumentation-key");
});

var kernel = Kernel.CreateBuilder()
    .AddAzureOpenAIChatCompletion(...)
    .Build();

kernel.LoggerFactory = loggerFactory;

监控指标 #

csharp

kernel.FunctionInvoked += (sender, e) =>
{
    var usage = e.Result.Metadata?["Usage"] as Dictionary<string, object>;
    
    _metricsService.RecordTokenUsage(
        model: "gpt-4",
        promptTokens: (int)usage["PromptTokens"],
        completionTokens: (int)usage["CompletionTokens"]
    );
};

最佳实践 #

1. 使用托管标识 #

csharp

// 生产环境推荐使用托管标识
var credential = new DefaultAzureCredential();

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    credentials: credential
);

2. 配置重试策略 #

csharp

var retryPolicy = new HttpRetryStrategyOptions
{
    MaxRetryAttempts = 3,
    BackoffType = DelayBackoffType.Exponential,
    Delay = TimeSpan.FromSeconds(2)
};

var httpClient = new HttpClient(
    new ResilienceHandler(retryPolicy)
    {
        InnerHandler = new HttpClientHandler()
    }
);

3. 成本管理 #

csharp

// 选择合适的部署 SKU
// Standard: 适合一般工作负载
// Provisioned: 适合稳定高并发

// 监控和限制 Token 使用
var settings = new OpenAIPromptExecutionSettings
{
    MaxTokens = 500  // 限制输出长度
};

4. 安全配置 #

csharp

// 使用 Azure Key Vault 存储密钥
var keyVaultUrl = "https://your-vault.vault.azure.net/";
var secretClient = new SecretClient(
    new Uri(keyVaultUrl),
    new DefaultAzureCredential()
);

var apiKey = (await secretClient.GetSecretAsync("OpenAI-ApiKey")).Value.Value;

builder.AddAzureOpenAIChatCompletion(
    deploymentName: "gpt-4-deployment",
    endpoint: "https://your-resource.openai.azure.com/",
    apiKey: apiKey
);

下一步 #

现在你已经掌握了 Azure OpenAI 连接器，接下来学习其他 LLM 连接器，了解如何连接更多 AI 服务！