Azure AI Foundry

Hermes Agent 将 Azure AI Foundry（以及 Azure OpenAI）作为一等提供商支持。单个 Azure 资源可以托管使用两种不同通信格式的模型：

OpenAI 风格 — POST /v1/chat/completions，端点形如 https://<resource>.openai.azure.com/openai/v1。用于 GPT-4.x、GPT-5.x、Llama、Mistral 及大多数开放权重模型。
Anthropic 风格 — POST /v1/messages，端点形如 https://<resource>.services.ai.azure.com/anthropic。当 Azure Foundry 通过 Anthropic Messages API 格式提供 Claude 模型时使用。

设置向导会探测你的端点，并自动检测所使用的传输协议、可用部署以及每个模型的上下文长度。

前提条件

至少包含一个部署的 Azure AI Foundry 或 Azure OpenAI 资源
该资源的 API 密钥（可在 Azure 门户的"密钥和端点"中获取）
部署的端点 URL

快速开始

hermes model
# → Select "Azure Foundry"
# → Enter your endpoint URL
# → 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)

向导将会：

嗅探 URL 路径 — 以 /anthropic 结尾的 URL 被识别为 Azure Foundry Claude 路由。
探测 GET <base>/models — 如果端点返回 OpenAI 格式的模型列表，Hermes 切换到 chat_completions 并用返回的部署 ID 预填选择器。
探测 Anthropic Messages 格式 — 用于不公开 /models 但接受 Anthropic Messages 格式的端点的后备方案。
回退到手动输入 — 拒绝所有探测的私有/受限端点仍然有效；你手动选择 API 模式并输入部署名称。

所选模型的上下文长度通过 Hermes 的标准元数据链（models.dev、提供商元数据和硬编码系列后备值）解析，并存储在 config.yaml 中，使模型能够正确调整自身的上下文窗口大小。

配置（写入 `config.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

以及 ~/.hermes/.env 中：

AZURE_FOUNDRY_API_KEY=<your-azure-key>

OpenAI 风格端点（GPT、Llama 等）

Azure OpenAI 的 v1 GA 端点接受标准 openai Python 客户端，改动极少：

model:
  provider: azure-foundry
  base_url: https://my-resource.openai.azure.com/openai/v1
  api_mode: chat_completions
  default: gpt-5.4

重要行为：

GPT-5.x、codex 和 o 系列自动路由到 Responses API。 Azure Foundry 将 GPT-5 / codex / o1 / o3 / o4 模型部署为仅 Responses API——对它们调用 /chat/completions 会返回 400 "The requested operation is unsupported."。Hermes 按名称检测这些模型系列，并透明地将 api_mode 升级为 codex_responses，即使 config.yaml 中仍显示 api_mode: chat_completions。GPT-4、GPT-4o、Llama、Mistral 及其他部署仍使用 /chat/completions。
max_completion_tokens 自动使用。 Azure OpenAI（与直接 OpenAI 一样）对 gpt-4o、o 系列和 gpt-5.x 模型需要 max_completion_tokens。Hermes 根据端点发送正确的参数。
需要 api-version 的旧版端点。 如果你有形如 https://<resource>.openai.azure.com/openai?api-version=2025-04-01-preview 的旧版基础 URL，Hermes 会提取查询字符串，并通过 default_query 在每个请求中转发（否则 OpenAI SDK 在连接路径时会丢弃它）。

Anthropic 风格端点（通过 Azure Foundry 使用 Claude）

对于 Claude 部署，使用 Anthropic 风格路由：

model:
  provider: azure-foundry
  base_url: https://my-resource.services.ai.azure.com/anthropic
  api_mode: anthropic_messages
  default: claude-sonnet-4-6

重要行为：

从基础 URL 中去除 /v1。 Anthropic SDK 在每个请求 URL 后追加 /v1/messages——Hermes 在将 URL 传递给 SDK 之前删除任何尾部的 /v1，以避免双重 /v1 路径。
api-version 通过 default_query 发送，而非追加到 URL。 Azure Anthropic 需要 api-version 查询字符串。将其嵌入基础 URL 会产生形如 /anthropic?api-version=.../v1/messages 的畸形路径并返回 404。Hermes 通过 Anthropic SDK 的 default_query 传递 api-version=2025-04-15。
禁用 OAuth 令牌刷新。 Azure 部署使用静态 API 密钥。适用于 Anthropic Console 的 ~/.claude/.credentials.json OAuth 令牌刷新循环对 Azure 端点明确跳过，以防止 Claude Code OAuth 令牌在会话中途覆盖你的 Azure 密钥。

备选方案：`provider: anthropic` + Azure 基础 URL

如果你已配置 provider: anthropic 并只想将其指向 Azure AI Foundry 使用 Claude，可以完全跳过 azure-foundry 提供商：

model:
  provider: anthropic
  base_url: https://my-resource.services.ai.azure.com/anthropic
  key_env: AZURE_ANTHROPIC_KEY
  default: claude-sonnet-4-6

将 AZURE_ANTHROPIC_KEY 设置在 ~/.hermes/.env 中。Hermes 检测到基础 URL 中包含 azure.com 时，会绕过 Claude Code OAuth 令牌链，直接使用 Azure 密钥进行 x-api-key 认证。

key_env 是标准蛇形命名字段；api_key_env（以及驼峰命名的 keyEnv / apiKeyEnv）作为别名接受。如果同时设置了 key_env 和 AZURE_ANTHROPIC_KEY/ANTHROPIC_API_KEY，key_env 命名的环境变量优先。

模型发现

Azure 不公开纯 API 密钥端点来列出你已部署的模型。部署枚举需要 Azure 资源管理器认证（az cognitiveservices account deployment list）和 Azure AD 主体，而非推理 API 密钥。

Hermes 能做到的：

Azure OpenAI v1 端点（<resource>.openai.azure.com/openai/v1）通过 GET /models 公开资源的可用模型目录。Hermes 使用此列表预填模型选择器。
Azure Foundry /anthropic 路由：通过 URL 路径检测，模型名称手动输入。
私有/防火墙后端点：手动输入，并显示友好的"无法探测"消息。

你始终可以直接输入部署名称——Hermes 不会对照返回的列表进行验证。

环境变量

变量	用途
`AZURE_FOUNDRY_API_KEY`	Azure AI Foundry / Azure OpenAI 的主要 API 密钥
`AZURE_FOUNDRY_BASE_URL`	端点 URL（通过 `hermes model` 设置；环境变量作为后备）
`AZURE_ANTHROPIC_KEY`	由 `provider: anthropic` + Azure 基础 URL 使用（`ANTHROPIC_API_KEY` 的替代）

故障排除

gpt-5.x 部署出现 401 未授权。 Azure 通过 /chat/completions 提供 gpt-5.x，而非 /responses。当 URL 包含 openai.azure.com 时，Hermes 自动处理此情况，但如果你看到带有 Invalid API key 正文的 401，请检查 config.yaml 中的 api_mode 是否为 chat_completions。

/v1/messages?api-version=.../v1/messages 出现 404。 这是修复前 Azure Anthropic 设置中畸形 URL 的问题。升级 Hermes——api-version 参数现在通过 default_query 传递，而非嵌入基础 URL，因此 SDK 在 URL 连接时无法破坏它。

向导显示"Auto-detection incomplete." 端点拒绝了 /models 探测和 Anthropic Messages 探测两者。这对于防火墙后或有 IP 白名单的私有端点来说是正常现象。回退到手动 API 模式选择并输入你的部署名称——一切仍然有效，只是 Hermes 无法预填选择器。

选择了错误的传输协议。 再次运行 hermes model，向导会重新探测。如果探测仍然选择了错误的模式，你可以直接编辑 config.yaml：

model:
  provider: azure-foundry
  api_mode: anthropic_messages   # or chat_completions

前提条件​

快速开始​

配置（写入 config.yaml）​

OpenAI 风格端点（GPT、Llama 等）​

Anthropic 风格端点（通过 Azure Foundry 使用 Claude）​

备选方案：provider: anthropic + Azure 基础 URL​

模型发现​

环境变量​

故障排除​

相关内容​