Sửa lỗi Azure OpenAI 404: Khắc phục lỗi 'DeploymentNotFound'

Vấn đề: Cách đặt tên của Azure OpenAI so với OpenAI tiêu chuẩn

Việc chuyển từ API trực tiếp của OpenAI sang Azure OpenAI thường mang lại cảm giác tương đương, nhưng có một quy ước đặt tên cụ thể khiến hầu hết mọi người gặp rắc rối. Bạn đã có sẵn API key. Endpoint của bạn đã được xác minh. Bạn biết chắc chắn rằng GPT-4o đang hoạt động trong khu vực của mình, chẳng hạn như eastus hoặc swedencentral. Tuy nhiên, khi bạn chạy script, SDK lại báo lỗi 404.

openai.NotFoundError: Error code: 404 - {'error': {'code': 'DeploymentNotFound', 'message': 'The model deployment at ID gpt-4o does not exist.'}}

Cốt lõi của vấn đề nằm ở cách Azure định danh các mô hình. Với API OpenAI trực tiếp, tham số model đề cập đến engine cơ sở, chẳng hạn như gpt-4o. Azure thì khác. Trong mã nguồn Azure của bạn, tham số model phải khớp với Deployment Name (Tên triển khai) mà bạn đã tạo trong Azure AI Studio. Việc mô hình cơ sở là gì không quan trọng; SDK chỉ quan tâm đến nhãn cụ thể đó.

Quy trình gỡ lỗi

Tôi đã mất khoảng 20 phút để kiểm tra lại các biến môi trường trước khi nhận ra vấn đề không phải ở thông tin xác thực (credentials). Tôi đã đặt tên cho bản triển khai của mình là gpt-4o-prod-01 trong portal, nhưng mã của tôi vẫn đang tìm kiếm gpt-4o. Đó là một sự không khớp đơn giản, nhưng đủ để làm gián đoạn kết nối.

Thư viện openai-python (v1.0.0+) coi đối số model là một con trỏ tới một deployment ID cụ thể. Nếu các chuỗi này không khớp chính xác từng ký tự, Azure gateway không thể điều hướng yêu cầu của bạn. Nó trả về lỗi 404 vì theo đúng nghĩa đen, nó không thể tìm thấy một compute instance nào có tên đó.

Các nguyên nhân phổ biến gây ra lỗi này:

Tên triển khai trong Azure AI Studio khác với chuỗi ký tự trong script Python của bạn.
Bản triển khai của bạn nằm trong một tài nguyên Azure khác với tài nguyên mà endpoint của bạn đang trỏ tới.
Mô hình vẫn đang ở trạng thái 'Provisioning' (Đang khởi tạo) và chưa sẵn sàng để tiếp nhận lưu lượng truy cập.

Giải pháp: Đồng bộ hóa tên triển khai của bạn

Để khắc phục điều này, bạn cần truy cập nhanh vào Azure portal để đồng bộ hóa các định danh của mình.

1. Xác minh tên trong Azure AI Studio

Đăng nhập vào Azure AI Studio và nhấp vào tab Deployments. Hãy nhìn kỹ vào cột Deployment name. Chính xác chuỗi ký tự này—bao gồm cả dấu gạch nối và dấu gạch dưới—là những gì mã của bạn cần.

Ví dụ: nếu bạn đặt tên cho bản triển khai của mình là marketing-gpt4-v1, bạn phải sử dụng chính xác chuỗi đó trong script của mình.

2. Cập nhật mã Python của bạn

Kiểm tra việc khởi tạo client AzureOpenAI của bạn. Đảm bảo lệnh gọi create sử dụng tên triển khai từ portal. Dưới đây là một ví dụ hoạt động hoàn chỉnh:

import os
from openai import AzureOpenAI

# Khởi tạo client với thông tin tài nguyên của bạn
client = AzureOpenAI(
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"), 
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2024-08-01-preview" # Sử dụng một phiên bản API ổn định, hiện hành
)

# SAI: model="gpt-4o"
# ĐÚNG: model="tên-triển-khai-thực-tế-của-bạn"

response = client.chat.completions.create(
    model="gpt-4o-prod-01", # Giá trị này PHẢI khớp với Deployment Name trong Azure
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Test connection."}
    ]
)

print(response.choices[0].message.content)

3. Kiểm tra tính tương thích của phiên bản API

Việc sử dụng một api_version cũ đôi khi có thể gây ra lỗi điều hướng với các mô hình mới hơn như GPT-4o. Nếu bạn vẫn gặp lỗi, hãy kiểm tra tài liệu Azure OpenAI để biết chuỗi phiên bản mới nhất. Các giá trị như 2024-02-01 hoặc 2024-08-01-preview là những lựa chọn phổ biến cho các bản triển khai hiện đại.

Xác minh: Liệt kê các bản triển khai của bạn bằng mã

Nếu bạn muốn ngừng việc đoán mò, hãy sử dụng một script hỗ trợ nhỏ để xem chính xác những gì Azure ghi nhận. Điều này xác nhận API key của bạn hoạt động và liệt kê mọi deployment ID hiện đang hoạt động trên tài nguyên của bạn.

import os
import requests

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
api_key = os.getenv("AZURE_OPENAI_API_KEY")
url = f"{endpoint}/openai/deployments?api-version=2024-02-01"

headers = {"api-key": api_key}

response = requests.get(url, headers=headers)
if response.status_code == 200:
    data = response.json()["data"]
    for deployment in data:
        print(f"Deployment ID hợp lệ: {deployment['id']} | Mô hình cơ sở: {deployment['model']}")
else:
    print(f"Lỗi khi lấy dữ liệu: {response.status_code}")

Tóm tắt các phương pháp hay nhất

Azure OpenAI yêu cầu một tư duy hơi khác so với API OpenAI tiêu chuẩn. Hãy ghi nhớ những quy tắc sau để tránh lỗi 404 trong tương lai:

Model Name so với Deployment ID: Luôn coi tham số model là một deployment_id.
Sử dụng biến môi trường: Tránh việc viết cứng (hardcoding) tên triển khai. Hãy lưu chúng trong một biến như AZURE_DEPLOYMENT_ID để bạn có thể chuyển đổi giữa môi trường 'dev' và 'prod' một cách dễ dàng.
Kiểm tra tính khả dụng theo vùng: Đảm bảo vùng tài nguyên của bạn (ví dụ: uksouth) thực sự hỗ trợ phiên bản mô hình cụ thể mà bạn muốn triển khai.