Azure Open OpenAI

本指南介绍如何配置和使用 Azure OpenAI 模型。

添加依赖

在 pom.xml 中添加 Azure OpenAI 依赖：

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-azure-openai</artifactId>
</dependency>

配置 Azure OpenAI

在 application.yml 中配置 Azure OpenAI：

spring:
  ai:
    azure:
      openai:
        api-key: your-api-key
        chat:
          options:
            deployment-name: gpt-4o-latest
            temperature: 0.7
            max-tokens: 2000
        endpoint: https://your-resource-name.openai.azure.com/
        embedding:
          options:
            deployment-name: embedding-ada-002
            dimensions: 1536

配置项说明

配置项	类型	说明
api-key	String	Azure OpenAI API 密钥
endpoint	String	Azure OpenAI 端点 URL
chat.options.deployment-name	String	Chat 模型部署名称
chat.options.temperature	Double	生成温度（0-1）
chat.options.max-tokens	Integer	最大 token 数量
embedding.options.deployment-name	String	Embedding 模型部署名称
embedding.options.dimensions	Integer	向量维度

使用示例

基本使用

@RestController
@RequiredArgsConstructor
public class AzureOpenAiController {

    private final SpringSqlEngine sqlEngine;
    private final AzureOpenAiChatModel chatModel;

    @PostMapping("/query")
    public Object query(@RequestBody QueryRequest request) {
        String sql = sqlEngine.setChatModel(chatModel)
                .generateSql(request.getQuestion());
        
        return sqlEngine.executeSql(sql);
    }
}

自定义选项

@PostMapping("/query-with-options")
public Object queryWithOptions(@RequestBody QueryRequest request) {
    String sql = sqlEngine.setChatModel(chatModel)
            .setOptions(RagOptions.builder()
                    .topN(10)
                    .rerank(true)
                    .limitScore(0.3)
                    .build())
            .generateSql(request.getQuestion());
    
    return sqlEngine.executeSql(sql);
}

支持的模型

Chat 模型

• GPT-4o
• GPT-4o-mini
• GPT-4-turbo
• GPT-35-turbo
• GPT-35

Embedding 模型

• text-embedding-ada-002
• text-embedding-3-small
• text-embedding-3-large

获取 API 密钥

1. 登录 Azure Portal
2. 创建或选择 Azure OpenAI 资源
3. 在"密钥和端点"页面获取 API 密钥和端点 URL
4. 部署模型并获取部署名称

最佳实践

API 密钥管理

使用环境变量管理 API 密钥：

spring:
  ai:
    azure:
      openai:
        api-key: ${AZURE_OPENAI_API_KEY}

温度设置

• 低温度（0.1-0.3）: 生成更确定、更一致的 SQL
• 中温度（0.4-0.7）: 平衡创造性和准确性
• 高温度（0.8-1.0）: 生成更有创意的 SQL

Token设置

根据查询复杂度调整 max-tokens：

• 简单查询: 500-1000 tokens
• 复杂查询: 1500-2000 tokens

故障排除

常见问题

问题: 认证失败

解决方案: 检查 API 密钥和端点 URL 是否正确

问题: 模型未找到

解决方案: 确认模型已部署并使用正确的部署名称

问题: 请求超时

解决方案: 增加超时时间或检查网络连接

下一步

• 查看 Ollama 配置 了解 Ollama 模型
• 学习 其他模型 了解其他模型配置
• 探索 高级用法 了解高级特性