Xưởng đúc Microsoft

Nhà cung cấp azure-foundry của Hermes Agent hỗ trợ Microsoft Foundry (trước đây là Azure AI Foundry) và Azure OpenAI. Một tài nguyên Foundry có thể lưu trữ các mô hình với hai định dạng dây khác nhau:

• Phong cách OpenAI — POST /v1/chat/completions trên các điểm cuối như `https://<resource>.OpenAI.azure.com/OpenAI/v1

. Được sử dụng cho GPT-4.x, GPT-5.x, Llama, Mistral và hầu hết các mẫu có trọng lượng mở.

• Phong cách nhân loại — POST /v1/messages trên các điểm cuối như `https://<resource.services.ai.azure.com/Anthropic

. Được sử dụng khi Microsoft Foundry phục vụ các mô hình Claude thông qua định dạng API Thông điệp Anthropic.

Trình hướng dẫn thiết lập sẽ thăm dò điểm cuối của bạn và tự động phát hiện phương tiện vận chuyển nào được sử dụng, triển khai nào có sẵn và độ dài ngữ cảnh của từng mô hình.

Điều kiện tiên quyết

• Tài nguyên Microsoft Foundry hoặc Azure OpenAI có ít nhất một lần triển khai
• URL điểm cuối của việc triển khai
• Hoặc khóa API (từ Cổng thông tin Azure trong phần "Khóa và điểm cuối") hoặc vai trò Người dùng Azure AI RBAC trên tài nguyên Foundry nếu bạn định sử dụng Microsoft Entra ID (đường dẫn không cần khóa mà Microsoft khuyến nghị). Một số đối tượng thuê có thể thể hiện vai trò Người dùng sáng lập trong quá trình triển khai đổi tên của Microsoft.

Bắt đầu nhanh

Hermes model

# → Select "Azure Foundry"
# → Enter your endpoint URL
# → Choose Authentication:
#     1. API key
#     2. Microsoft Entra ID  (managed identity / workload identity / az login)
# → (Entra) Hermes probes DefaultAzureCredential; on success it never asks for a key
# → (API key) Enter your API key
# Hermes probes the endpoint and auto-detects transport + models
# → Pick a model from the list (or type a deployment name manually)

`
``Trình hướng dẫn sẽ:
1. **Đánh hơi đường dẫn URL** — Các URL kết thúc bằng 

/Anthropic
` được công nhận là tuyến Claude của Microsoft Foundry.
2. **Đầu dò 
`GET <base>/models

** — nếu điểm cuối trả về danh sách mô hình có hình dạng OpenAI, Hermes sẽ chuyển sang 
`chat_completions
` và điền sẵn ID triển khai được trả về vào bộ chọn.
3. **Thăm dò hình dạng Thông điệp Anthropic** — dự phòng cho các điểm cuối không hiển thị 

/models
` nhưng chấp nhận định dạng Thông điệp Anthropic.
4. **Quay lại chế độ nhập thủ công** — các điểm cuối riêng tư/có cổng từ chối mọi đầu dò vẫn hoạt động; bạn chọn chế độ API và nhập tên triển khai bằng tay.

Độ dài ngữ cảnh cho mô hình đã chọn được giải quyết thông qua chuỗi siêu dữ liệu tiêu chuẩn của Hermes (
`models.dev

, siêu dữ liệu của nhà cung cấp và dự phòng dòng được mã hóa cứng) và được lưu trữ trong 
`config.yaml
` để mô hình có thể định cỡ chính xác cửa sổ ngữ cảnh của chính nó.

## Microsoft Entra ID (không cần chìa khóa, RBAC) — được đề xuất

Microsoft khuyến nghị [keyless authentication with Microsoft Entra ID](https://learn.Microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) cho khối lượng công việc sản xuất của Foundry. Hermes hỗ trợ Entra ID cho **cả hai** bề mặt API:
- **Phong cách OpenAI** (
`API_mode: chat_completions
` / 
`Codex_responses

) — GPT-4/5, Llama, Mistral, DeepSeek, v.v.
- **Phong cách nhân loại** (
`API_mode: Anthropic_messages

) — Mô hình Claude trên Microsoft Foundry.

RBAC của Foundry được tính theo từng tài nguyên (
`Azure AI User
` cấp cho cả hai bề mặt; một số đối tượng thuê có thể hiển thị 
`Foundry User

) và Microsoft ghi lại cùng một phạm vi suy luận (
`https://ai.azure.com/.default

) cho cả hai. Dưới mui xe:
- Kiểu OpenAI sử dụng hợp đồng 
`API_key=
` có thể gọi gốc của OpenAI Python SDK — SDK tự động tạo ra JWT mới cho mỗi yêu cầu.
- Kiểu Anthropic sử dụng 
`httpx.CLIent
` với móc sự kiện yêu cầu được cài đặt bởi 
`agent.azure_identity_adapter.build_bearer_http_CLIent

, vì SDK Anthropic vốn không chấp nhận 
`auth_token
` có thể gọi được. Móc viết lại 
`Authorization: Bearer <fresh-JWT
` cho mỗi yêu cầu gửi đi. Cùng một Microsoft RBAC, cùng phạm vi Foundry - hợp đồng SDK là điểm khác biệt duy nhất.

### Tại sao nên sử dụng ID Entra?
- Không có khóa API tồn tại lâu dài để xoay hoặc thu hồi.
- Quyền truy cập dựa trên RBAC — cấp hoặc xóa 
`Azure AI User
` trên tài nguyên Foundry, không cần viết lại cấu hình.
- Nhật ký truy cập và kiểm tra được phân đoạn theo người được chuyển nhượng thay vì tất cả người gọi chia sẻ một khóa tĩnh.
- Bề mặt xác thực duy nhất cho máy ảo Azure, nhóm AKS, Dịch vụ ứng dụng, Chức năng, Ứng dụng vùng chứa và Dịch vụ đại lý đúc thông qua danh tính được quản lý.
- Nhận dạng khối lượng công việc và các luồng dịch vụ chính cho đường ống CI/CD.

### Thiết lập một lần (phía Azure)
1. Trong Cổng thông tin Azure, hãy mở tài nguyên Foundry của bạn → **Kiểm soát quyền truy cập (IAM)** → **Thêm → Thêm phân công vai trò**.
2. Chọn vai trò **Người dùng Azure AI** (hoặc **Người dùng sáng lập** nếu đối tượng thuê của bạn có vai trò đã được đổi tên).
3. Gán nó cho:
   - **Tài khoản người dùng của bạn** để phát triển cục bộ với 
`az login

.
   - **Danh tính được quản lý hoặc danh tính khối lượng công việc** cho điện toán được lưu trữ trên máy chủ Azure (được khuyến nghị cho sản xuất).
   - **Dịch vụ Đại lý Foundry đã lưu trữ danh tính đại lý của đại lý** khi Hermes chạy bên trong một đại lý được lưu trữ.
   - **Một dịch vụ chính** dành cho quy trình CI/CD khi không có danh tính khối lượng công việc.
4. Đợi ~5 phút để vai trò được phổ biến.

Azure CLI tương đương:

``` bash
az role assignment create \

  --assignee <principal-or-agent-identity-CLIent-id \
  --role "Azure AI User" \
  --scope <foundry-resource-id

`

### Thiết lập một lần (phía Hermes)

``` bash
Hermes model

# → Select "Azure Foundry"
# → Enter your endpoint URL
# → Authentication: 2 (Microsoft Entra ID)
# → (optional) user-assigned managed identity CLIent ID
# → (optional) Azure tenant ID
# → Hermes probes DefaultAzureCredential() and reports which inner
#    credential succeeded (e.g. AzureCLICredential, ManagedIdentityCredential)

`
`Trình hướng dẫn chạy thăm dò giới hạn ánh sáng trước (thời gian chờ 10 giây). Nếu không thành công, nó đề xuất "vẫn lưu, xác thực sau" — hữu ích khi định cấu hình trên máy chưa có thông tin xác thực nhưng sẽ có trong thời gian chạy (ví dụ: chuẩn bị cấu hình để triển khai danh tính được quản lý).

azure-identity
` được cài đặt tự động trong lần sử dụng đầu tiên thông qua đường dẫn cài đặt lười biếng của Hermes. Để cài đặt trước:

``` bash
pip install azure-identity

`

### Cấu hình được ghi vào 
`config.yaml

`
`YAML
model:
  provider: azure-foundry
  base_url: https://my-resource.OpenAI.azure.com/OpenAI/v1
  API_mode: chat_completions
  auth_mode: entra_id
  default: GPT-4o
  context_length: 128000
  entra:
    scope: https://ai.azure.com/.default        # only when overriding the default

`
``Hermes chỉ quản lý một núm dành riêng cho Entra trong 
`config.yaml

:
- **
`scope

`
** — phạm vi tài nguyên OAuth. Mặc định cho phạm vi suy luận được ghi lại của Microsoft (
`https://ai.azure.com/.default

). Chỉ ghi đè nếu tài nguyên của bạn được cung cấp cho đối tượng không chuẩn.

Mọi thứ khác (đối tượng thuê, bí mật chính của dịch vụ, tệp mã thông báo liên kết, cơ quan đám mây có chủ quyền, tùy chọn của nhà môi giới) đều được 
`azure-identity
` đọc trực tiếp từ các biến môi trường 
`AZURE_*
` tiêu chuẩn — xem [credential resolution order](#credential-resolution-order) bên dưới. Đặt những thứ đó trong 

~/.Hermes/.env
` hoặc môi trường triển khai của bạn, chính xác như tài liệu tham khảo SDK của Microsoft mô tả.

Không có bí mật nào xảy ra trong 

~/.Hermes/.env
` cho chế độ Entra - 
`azure-identity
` lưu trữ mã thông báo trong quá trình xử lý (và nếu có, trong chuỗi khóa hệ điều hành của bạn / 

~/.IdentityService

).

### Thứ tự giải quyết thông tin xác thực``azure-identity
` 
`DefaultAzureCredential
` của XPROTECTX thực hiện chuỗi này theo từng yêu cầu mã thông báo, dừng ở thông tin xác thực đầu tiên trả về mã thông báo:
1. **Thông tin xác thực về môi trường** — 
`AZURE_TENANT_ID

 + 
`AZURE_CLIENT_ID

 + 
`AZURE_CLIENT_SECRET
` (hoặc 
`AZURE_CLIENT_CERTIFICATE_PATH
` / 
`AZURE_FEDERATED_TOKEN_FILE

).
2. **Nhận dạng khối lượng công việc** — 
`AZURE_FEDERATED_TOKEN_FILE
` (Mã thông báo liên kết AKS / OIDC).
3. **Nhận dạng được quản lý** — Điểm cuối IMDS (
`169.254.169.254

) cho máy ảo; 
`IDENTITY_ENDPOINT
` dành cho Dịch vụ ứng dụng / Chức năng / Ứng dụng vùng chứa. Các đại lý được lưu trữ của Dịch vụ Đại lý Foundry sử dụng danh tính đại lý được lưu trữ.
4. **Visual Studio Code** — Tiện ích mở rộng tài khoản Azure.
5. **Azure CLI** — phiên 
`az login

.
6. **Azure Developer CLI** — 
`azd auth login

.
7. **Azure PowerShell** — 
`Connect-AzAccount

.
8. **Nhà môi giới** (chỉ dành cho Windows / WSL) — Trình quản lý tài khoản web.

Theo mặc định, thông tin xác thực của trình duyệt tương tác bị loại trừ đối với các lần chạy Hermes không được giám sát; thay vào đó hãy sử dụng Azure CLI, Azure Developer CLI, danh tính được quản lý, danh tính khối lượng công việc hoặc thông tin xác thực chính của dịch vụ.

### Các mẫu triển khai`**Phát triển địa phương:**

`
``` bash
az login
Hermes model   # pick Azure Foundry → Entra ID
Hermes         # uses your az login token

`
``**Azure VM / Chức năng / Dịch vụ ứng dụng / Ứng dụng vùng chứa (danh tính được quản lý do hệ thống chỉ định):**

1. Kích hoạt danh tính do hệ thống chỉ định trên tài nguyên điện toán.
2. Cấp danh tính 
`Azure AI User
` (hoặc 
`Foundry User

) trên tài nguyên Foundry.
3. Đặt 
`model.auth_mode: entra_id
` trong config.yaml - không cần vars env.

**Azure VM / Chức năng / Dịch vụ ứng dụng / Ứng dụng vùng chứa (danh tính được quản lý do người dùng chỉ định):**
- Đặt 
`AZURE_CLIENT_ID
` thành ID khách hàng của danh tính do người dùng chỉ định để 
`DefaultAzureCredential
` chọn đúng.

**Đại lý lưu trữ Dịch vụ Đại lý Foundry:**
- Tạo tác nhân được lưu trữ và cấp danh tính của tác nhân đó 
`Azure AI User
` (hoặc 
`Foundry User

) trên tài nguyên Foundry. Hermes sử dụng 
`ManagedIdentityCredential
` từ bên trong đại lý được lưu trữ; việc phân công vai trò thuộc về danh tính tác nhân, không chỉ dự án mẹ hoặc người dùng của bạn.

**Nhận dạng khối lượng công việc AKS (thay thế nhận dạng nhóm AAD):**
- Chú thích tài khoản dịch vụ của nhóm bằng ID khách hàng nhận dạng khối lượng công việc.
- Tệp mã thông báo liên kết của nhóm được tự động phát hiện thông qua 
`AZURE_FEDERATED_TOKEN_FILE

.
- 
`model.auth_mode: entra_id
` hoạt động mà không cần thay đổi cấu hình thêm.

**Dịch vụ chính trong CI:**
- Đặt 
`AZURE_TENANT_ID

, 
`AZURE_CLIENT_ID

, 
`AZURE_CLIENT_SECRET
` trong môi trường chạy.

#### Mây chủ quyền (Chính phủ, Trung Quốc)

Xuất 
`AZURE_AUTHORITY_HOST
` (ví dụ: 
`https://login.Microsoftonline.us
` cho Azure Government, 
`https://login.partner.Microsoftonline.cn
` cho Azure Trung Quốc). 
`azure-identity
` đọc trực tiếp.`###Kiểm tra sức khỏe``Hermes doctor
` chạy thăm dò 10 giây đối với 
`DefaultAzureCredential
` khi 
`model.auth_mode: entra_id

, báo cáo thông tin xác thực bên trong nào đã giành được (có các biến env, điểm cuối nhận dạng được quản lý có thể truy cập, v.v.).

Hermes auth
` hiển thị khối trạng thái có cấu trúc:

`
azure-foundry (Microsoft Entra ID):
  Endpoint: https://my-resource.OpenAI.azure.com/OpenAI/v1
  Scope: https://ai.azure.com/.default
  Status: configured; live token probe is skipped here

`

### Hạn chế- **Điểm cuối kiểu Anthropic sử dụng móc sự kiện httpx.** SDK Anthropic Python không chấp nhận nguyên bản 
`auth_token
` có thể gọi được (≤ 0,86,0). Hermes cài đặt một móc sự kiện yêu cầu trên 
`httpx.CLIent
` tùy chỉnh để tạo ra JWT mới cho mỗi yêu cầu gửi đi và viết lại 
`Authorization: Bearer <JWT

. Điều này có chức năng tương đương với hợp đồng 
`Callable[[], str]
` gốc của OpenAI SDK nhưng thêm một lớp gián tiếp. Nếu SDK Anthropic bổ sung hỗ trợ xác thực có thể gọi được hạng nhất trong bản phát hành trong tương lai, Hermes sẽ chuyển sang sử dụng tính năng này một cách minh bạch.
- **Các công việc hàng loạt và 
`multiprocessing.Pool

.** Nhà cung cấp mã thông báo Entra là một công cụ đóng không thể được xử lý qua các ranh giới quy trình. 
`batch_runner.py
` tự động loại bỏ lệnh gọi khỏi cấu hình công nhân và cho phép mỗi quy trình công nhân xây dựng lại nhà cung cấp của riêng mình từ 
`config.yaml
` — không yêu cầu người dùng thực hiện hành động nào nhưng mỗi công nhân phải trả một lần đi bộ khi khởi động.
- **Không có sự tồn tại của JWT mang tên trong 
`auth.JSON

.** Hermes không sao chép bộ nhớ đệm mã thông báo nội bộ của 
`azure-identity

; khởi động nguội thực hiện chuỗi thông tin xác thực theo suy luận đầu tiên.

## Cấu hình (được ghi vào 
`config.yaml

)

Sau khi chạy trình hướng dẫn, bạn sẽ thấy một cái gì đó như thế này:

``` yaml
model:
  provider: azure-foundry
  base_url: https://my-resource.OpenAI.azure.com/OpenAI/v1
  API_mode: chat_completions         # or "Anthropic_messages"
  default: GPT-5.4-mini              # your deployment / model name
  context_length: 400000             # auto-detected

`
``Và trong 

~/.Hermes/.env

:

`
AZURE_FOUNDRY_API_KEY=<your-azure-key

`

## Điểm cuối kiểu OpenAI (GPT, Llama, v.v.)

Điểm cuối v1 GA của Azure OpenAI chấp nhận ứng dụng khách Python 
`OpenAI
` tiêu chuẩn với những thay đổi tối thiểu:

`YAML
model:
  provider: azure-foundry
  base_url: https://my-resource.OpenAI.azure.com/OpenAI/v1
  API_mode: chat_completions
  default: GPT-5.4

`
``Hành vi quan trọng:
- **GPT-5.x, Codex và o-series tự động định tuyến tới API phản hồi.** Microsoft Foundry triển khai các mô hình GPT-5 / Codex / o1 / o3 / o4 dưới dạng chỉ dành cho API phản hồi — gọi 

/chat/completions
` đối với chúng sẽ trả về 
`400 "The requested operation is unsupported."

. Hermes phát hiện các dòng mẫu này theo tên và nâng cấp 
`API_mode
` lên 
`Codex_responses
` một cách minh bạch, ngay cả khi 
`config.yaml
` vẫn đọc 
`API_mode: chat_completions

. GPT-4, GPT-4o, Llama, Mistral và các triển khai khác vẫn nằm trên 

/chat/completions

.

- **
`max_completion_tokens
` được sử dụng tự động.** Azure OpenAI (như OpenAI trực tiếp) yêu cầu 
`max_completion_tokens
` cho các mẫu GPT-4o, o-series và GPT-5.x. Hermes gửi tham số phù hợp dựa trên điểm cuối.
- **Các điểm cuối phiên bản trước yêu cầu 
`API-version

.** Nếu bạn có URL cơ sở cũ như 
`https://<resource.OpenAI.azure.com/OpenAI?API-version=2025-04-01-preview

, Hermes sẽ trích xuất chuỗi truy vấn và chuyển tiếp chuỗi đó qua 
`default_query
` theo mọi yêu cầu (nếu không thì OpenAI SDK sẽ loại bỏ chuỗi đó khi nối các đường dẫn).

## Điểm cuối kiểu nhân loại (Claude qua Microsoft Foundry)

Để triển khai Claude, hãy sử dụng lộ trình kiểu Anthropic:

``` yaml
model:
  provider: azure-foundry
  base_url: https://my-resource.services.ai.azure.com/Anthropic
  API_mode: Anthropic_messages
  default: Claude-sonnet-4-6

`
``Hành vi quan trọng:
- **

/v1
` bị loại bỏ khỏi URL cơ sở.** Anthropic SDK gắn thêm 

/v1/messages
` vào mọi URL yêu cầu — Hermes xóa mọi 

/v1
` còn sót lại trước khi chuyển URL tới SDK để tránh các đường dẫn 

/v1
` kép.

- **
`API-version
` được gửi qua 
`default_query

, không được thêm vào URL.** Azure Anthropic yêu cầu chuỗi truy vấn 
`API-version

. Việc đưa nó vào URL cơ sở sẽ tạo ra các đường dẫn không đúng định dạng như 

/Anthropic?API-version=.../v1/messages
` và trả về 404. Thay vào đó, Hermes chuyển 
`API-version=2025-04-15
` thông qua 
`default_query
` của Anthropic SDK.
- **Bearer auth được sử dụng thay vì 
`x-API-key

.** Tuyến đường tương thích với Anthropic của Azure yêu cầu 
`Authorization: Bearer <key
` thay vì tiêu đề 
`x-API-key
` gốc của Anthropic. Hermes phát hiện 
`azure.com
` trong URL cơ sở và định tuyến khóa API thông qua trường 
`auth_token
` của SDK để tiêu đề bên phải đạt đến thượng nguồn.
- **Tiêu đề beta của cửa sổ ngữ cảnh 1M được giữ lại.** Azure vẫn cổng ngữ cảnh Claude mã thông báo 1M (Opus 4.6/4.7, Sonnet 4.6) phía sau tiêu đề 
`Anthropic-beta: context-1m-2025-08-07

. Hermes giữ tiêu đề beta đó trên đường dẫn Azure (nó bị loại bỏ khỏi các yêu cầu OAuth gốc của Anthropic vì một số đăng ký từ chối nó, nhưng Azure yêu cầu nó).
- **Làm mới mã thông báo OAuth bị tắt.** Việc triển khai Azure sử dụng khóa API tĩnh. Vòng làm mới mã thông báo 

~/.Claude/.credentials.JSON
` OAuth áp dụng cho Bảng điều khiển Anthropic được bỏ qua rõ ràng đối với các điểm cuối Azure để ngăn mã thông báo Claude Code OAuth ghi đè khóa Azure của bạn giữa phiên.

## Thay thế: 
`provider: Anthropic

 + URL cơ sở Azure

Nếu bạn đã định cấu hình 
`provider: Anthropic
` và chỉ muốn trỏ nó tới Microsoft Foundry cho Claude, bạn có thể bỏ qua hoàn toàn nhà cung cấp 
`azure-foundry

:

``` yaml
model:
  provider: Anthropic
  base_url: https://my-resource.services.ai.azure.com/Anthropic
  key_env: AZURE_Anthropic_KEY
  default: Claude-sonnet-4-6

`
`Với 
`AZURE_Anthropic_KEY
` được đặt trong 

~/.Hermes/.env

. Hermes phát hiện 
`azure.com
` trong URL cơ sở và đoản mạch xung quanh chuỗi mã thông báo Claude Code OAuth nên khóa Azure được sử dụng trực tiếp với xác thực 
`x-API-key

.

key_env
` là tên trường snake_case chuẩn; 
`API_key_env
` (và CamelCase 
`keyEnv
` / 
`APIKeyEnv

) được chấp nhận làm bí danh. Nếu cả 
`key_env
` và 
`AZURE_Anthropic_KEY

/
`Anthropic_API_KEY
` đều được đặt, thì biến env có tên 
`key_env
` sẽ thắng.

## Khám phá mô hình

Azure **không** hiển thị điểm cuối khóa API thuần túy để liệt kê các hoạt động triển khai mô hình *đã triển khai* của bạn. Việc liệt kê triển khai yêu cầu xác thực Trình quản lý tài nguyên Azure (
`az cognitiveservices account deployment list

) bằng mã chính Azure AD, không phải khóa API suy luận.

Những gì Hermes có thể làm:
- Điểm cuối Azure OpenAI v1 (

<resource.OpenAI.azure.com/OpenAI/v1

) hiển thị 
`GET /models
` với danh mục mô hình **có sẵn** của tài nguyên. Hermes sử dụng danh sách này để điền trước bộ chọn mẫu.

- Các tuyến Microsoft Foundry 

/Anthropic

: được phát hiện qua đường dẫn URL, tên model được nhập thủ công.
- Điểm cuối riêng tư/được tường lửa: nhập thủ công với thông báo "không thể thăm dò" thân thiện.

Bạn luôn có thể nhập trực tiếp tên triển khai — Hermes không xác thực dựa trên danh sách được trả về.

## Biến môi trường

| Biến | Mục đích |
|----------|----------|
| 
`AZURE_FOUNDRY_API_KEY
` | Khóa API chính cho Microsoft Foundry / Azure OpenAI (chế độ API_key) |
| 
`AZURE_FOUNDRY_BASE_URL
` | URL điểm cuối (được đặt qua 
`Hermes model

; env var được sử dụng làm dự phòng) |
| 
`AZURE_Anthropic_KEY
` | Được sử dụng bởi 
`provider: Anthropic

 + URL cơ sở Azure (thay thế cho 
`Anthropic_API_KEY

) |
| 
`AZURE_TENANT_ID
` | Đối tượng thuê ID nhập cho các luồng dịch vụ chính |
| 
`AZURE_CLIENT_ID
` | ID ứng dụng khách Entra ID (chính dịch vụ, nhận dạng khối lượng công việc hoặc nhận dạng được quản lý do người dùng chỉ định) |
| 
`AZURE_CLIENT_SECRET
` | Bí mật chính của dịch vụ |
| 
`AZURE_CLIENT_CERTIFICATE_PATH
` | Chứng chỉ chính của dịch vụ (thay thế cho bí mật) |
| 
`AZURE_FEDERATED_TOKEN_FILE
` | Đường dẫn mã thông báo liên kết nhận dạng khối lượng công việc (AKS) |
| 
`AZURE_AUTHORITY_HOST
` | Ghi đè máy chủ có thẩm quyền trên đám mây có chủ quyền |
| 
`IDENTITY_ENDPOINT
` / 
`MSI_ENDPOINT
` | Điểm cuối nhận dạng được quản lý cho Dịch vụ ứng dụng, Chức năng và Ứng dụng vùng chứa; Thay vào đó, máy ảo thường sử dụng IMDS |

SDK Azure đọc trực tiếp các biến env 
`AZURE_*

. Hermes không bao giờ kiểm tra chúng ngoài việc báo cáo những nguồn nào có trong đầu ra 
`Hermes doctor

.

## Khắc phục sự cố`**401 Không được phép khi triển khai GPT-5.x.**
Azure phục vụ GPT-5.x trên 

/chat/completions

, không phải 

/responses

. Hermes tự động xử lý việc này khi URL chứa 
`OpenAI.azure.com

, nhưng nếu bạn thấy 401 có nội dung 
`Invalid API key

, hãy kiểm tra xem 
`API_mode
` trong 
`config.yaml
` của bạn có phải là 
`chat_completions
` hay không.

**404 trên 

/v1/messages?API-version=.../v1/messages

.**
Đây là lỗi URL không đúng định dạng từ quá trình thiết lập Azure Anthropic được sửa trước. Nâng cấp Hermes — tham số 
`API-version
` hiện được chuyển qua 
`default_query
` thay vì được đưa vào URL cơ sở, do đó SDK không thể làm hỏng tham số đó trong quá trình nối URL.

**Trình hướng dẫn nói "Tự động phát hiện chưa hoàn tất."**
Điểm cuối đã từ chối cả đầu dò 

/models
` và đầu dò Thông điệp nhân loại. Điều này là bình thường đối với các điểm cuối riêng tư phía sau tường lửa hoặc có danh sách IP cho phép. Quay lại lựa chọn chế độ API thủ công và nhập tên triển khai của bạn — mọi thứ vẫn hoạt động, Hermes chỉ không thể điền trước bộ chọn.

**Đã chọn sai phương tiện vận chuyển.**
Chạy lại 
`Hermes model
` và trình hướng dẫn sẽ thăm dò lại. Nếu đầu dò vẫn chọn sai chế độ, bạn có thể chỉnh sửa trực tiếp 
`config.yaml

:

``` yaml
model:
  provider: azure-foundry
  API_mode: Anthropic_messages   # or chat_completions

`
``**ID nhập: "chuỗi thông tin xác thực đã hết" hoặc 401 Không được phép sau khi chuyển sang 
`auth_mode: entra_id

.**

- Chạy 
`az login
` để làm mới phiên nhà phát triển của bạn (mã thông báo được lưu trong bộ nhớ cache có thể đã hết hạn).
- Xác minh việc gán vai trò 
`Azure AI User
` (hoặc 
`Foundry User

) đã có hiệu lực: 
`az role assignment list --assignee <user-or-identity-id
` phải liệt kê nó trên tài nguyên Foundry của bạn. Việc truyền bá vai trò có thể mất tới 5 phút.
- Đối với danh tính được quản lý do người dùng chỉ định, hãy kiểm tra kỹ 
`AZURE_CLIENT_ID
` có khớp với danh tính được đính kèm với tài nguyên điện toán hay không.
- Chạy 
`Hermes doctor
` — thăm dò Azure Entra báo cáo xem việc thu thập mã thông báo có thành công hay không và bao gồm gợi ý khắc phục.**ID nhập: đèn chiếu trước của trình hướng dẫn bị treo hoặc hết thời gian chờ.**
Kiểm tra trước 10 giây là kiểm tra mềm. Chọn "Vẫn lưu và xác thực sau" và chạy 
`Hermes doctor
` sau khi triển khai vào môi trường đích. Các nguyên nhân phổ biến bao gồm dịch vụ mã thông báo không thể truy cập hoặc trạng thái đăng nhập cục bộ cũ — ưu tiên nhận dạng khối lượng công việc trong CI, đặt 
`AZURE_TENANT_ID

+
`AZURE_CLIENT_ID

+
`AZURE_CLIENT_SECRET
` khi sử dụng dịch vụ chính hoặc chạy 
`az login
` để phát triển cục bộ.

**401 trên điểm cuối kiểu Anthropic với Entra ID.**
Xác minh rằng vai trò 
`Azure AI User
` (hoặc 
`Foundry User

) tương tự được chỉ định trên tài nguyên Foundry (nó bao gồm cả đường dẫn 

/OpenAI/v1
` và 

/Anthropic

). Nếu thăm dò kiểu OpenAI hoạt động trong trình hướng dẫn nhưng các yêu cầu 
`Claude-*
` không thành công trong thời gian chạy thì nguyên nhân phổ biến nhất là 
`model.entra.scope
` cũ còn sót lại từ lần chạy trình hướng dẫn trước đó — hãy xóa dòng 
`entra.scope
` khỏi 
`config.yaml
` để thời gian chạy quay trở lại phạm vi 
`https://ai.azure.com/.default
` mặc định.

## Liên quan
- [Environment variables](/docs/reference/environment-variables)
- [Configuration](/docs/user-guide/configuration)
- [AWS Bedrock](/docs/guides/aws-bedrock) — tích hợp nhà cung cấp đám mây lớn khác
- [Microsoft: Configure Entra ID for Foundry](https://learn.Microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) — tài liệu ngược dòng cho đường dẫn không cần chìa khóa