Azure AI 파운드리
Hermes Agent는 Azure AI Foundry(및 Azure OpenAI)를 일류 제공자로 지원합니다. 단일 Azure 리소스는 두 가지 서로 다른 연결 형식을 사용하여 모델을 호스팅할 수 있습니다.
- OpenAI 스타일 —
https://<resource>.openai.azure.com/openai/v1과 같은 엔드포인트의POST /v1/chat/completions. GPT-4.x, GPT-5.x, Llama, Mistral 및 대부분의 개방형 모델에 사용됩니다. - 인류 스타일 —
https://<resource>.services.ai.azure.com/anthropic과 같은 엔드포인트의POST /v1/messages. Azure Foundry가 Anthropic Messages API 형식을 통해 Claude 모델을 제공할 때 사용됩니다.
설정 마법사는 엔드포인트를 조사하고 엔드포인트가 사용하는 전송, 사용 가능한 배포, 각 모델의 컨텍스트 길이를 자동 감지합니다.
전제 조건
- 하나 이상의 배포가 포함된 Azure AI Foundry 또는 Azure OpenAI 리소스
- 해당 리소스에 대한 API 키(Azure Portal의 "키 및 엔드포인트" 아래에서 사용 가능)
- 배포의 엔드포인트 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-series는 Responses API로 자동 라우팅됩니다. Azure Foundry는 GPT-5/codex/o1/o3/o4 모델을 Responses-API 전용으로 배포합니다. 이에 대해
/chat/completions을 호출하면400 "The requested operation is unsupported."이 반환됩니다. Hermes는 이러한 모델 계열을 이름으로 감지하고config.yaml이 여전히api_mode: chat_completions을 읽는 경우에도api_mode을codex_responses으로 투명하게 업그레이드합니다. GPT-4, GPT-4o, Llama, Mistral 및 기타 배포는/chat/completions에 유지됩니다. max_completion_tokens은 자동으로 사용됩니다. Azure OpenAI(직접 OpenAI와 마찬가지로)에는 gpt-4o, o-시리즈 및 gpt-5.x 모델에max_completion_tokens이 필요합니다. 헤르메스는 엔드포인트를 기반으로 올바른 매개변수를 보냅니다.api-version이 필요한 이전 v1 엔드포인트.https://<resource>.openai.azure.com/openai?api-version=2025-04-01-preview과 같은 레거시 기본 URL이 있는 경우 Hermes는 쿼리 문자열을 추출하여 모든 요청에서default_query을 통해 전달합니다(그렇지 않으면 OpenAI SDK는 경로 조인 시 이를 삭제합니다).
인류 스타일 엔드포인트(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
중요한 행동:
/v1은 기본 URL에서 제거됩니다. Anthropic SDK는 모든 요청 URL에/v1/messages을 추가합니다. Hermes는 이중/v1경로를 피하기 위해 URL을 SDK에 전달하기 전에 모든 후행/v1을 제거합니다.api-version은 URL에 추가되지 않고default_query을 통해 전송됩니다. 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.jsonOAuth 토큰 새로 고침 루프는 Claude Code OAuth 토큰이 세션 중에 Azure 키를 덮어쓰는 것을 방지하기 위해 Azure 끝점에 대해 명시적으로 건너뜁니다.
대안: provider: anthropic + Azure 기본 URL
provider: anthropic이 이미 구성되어 있고 이를 Claude용 Azure AI Foundry를 가리키려는 경우 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`은 표준 snake_case 필드 이름입니다. `api_key_env`(및 camelCase `keyEnv` / `apiKeyEnv`)은 별칭으로 허용됩니다. `key_env` 및 `AZURE_ANTHROPIC_KEY`/`ANTHROPIC_API_KEY`이 모두 설정된 경우 `key_env` 이름의 env var가 우선합니다.
## 모델 발견 \{#model-discovery}
Azure는 *배포된* 모델 배포를 나열하기 위해 순수 API 키 엔드포인트를 노출하지 **않습니다**. 배포 열거에는 추론 API 키가 아닌 Azure AD 주체를 사용한 Azure Resource Manager 인증(`az cognitiveservices account deployment list`)이 필요합니다.
헤르메스가 할 수 있는 일:
- Azure OpenAI v1 엔드포인트(`<resource>.openai.azure.com/openai/v1`)는 리소스의 **사용 가능한** 모델 카탈로그와 함께 `GET /models`을 노출합니다. Hermes는 이 목록을 사용하여 모델 선택기를 미리 채웁니다.
- Azure Foundry `/anthropic` 경로: URL 경로를 통해 감지되었으며, 모델 이름은 수동으로 입력했습니다.
- 개인/방화벽 엔드포인트: 친숙한 "탐색할 수 없음" 메시지가 포함된 수동 입력.
언제든지 배포 이름을 직접 입력할 수 있습니다. Hermes는 반환된 목록에 대해 유효성을 검사하지 않습니다.
## 환경변수 \{#environment-variables}
| 변수 | 목적 |
|----------|---------|
| `AZURE_FOUNDRY_API_KEY` | Azure AI Foundry/Azure OpenAI용 기본 API 키 |
| `AZURE_FOUNDRY_BASE_URL` | 엔드포인트 URL(`hermes model`을 통해 설정, env var가 대체 수단으로 사용됨) |
| `AZURE_ANTHROPIC_KEY` | `provider: anthropic` + Azure 기본 URL(`ANTHROPIC_API_KEY` 대체)에서 사용됩니다. |
## 문제 해결 \{#troubleshooting}
**gpt-5.x 배포에서는 401 권한이 없습니다.**
Azure는 `/responses`이 아닌 `/chat/completions`에서 gpt-5.x를 제공합니다. Hermes는 URL에 `openai.azure.com`이 포함된 경우 이를 자동으로 처리하지만, `Invalid API key` 본문에 401이 표시되면 `config.yaml`의 `api_mode`이 `chat_completions`인지 확인하세요.
**`/v1/messages?api-version=.../v1/messages`의 404.**
이는 접두사 Azure Anthropic 설정의 잘못된 URL 버그입니다. Hermes 업그레이드 — `api-version` 매개변수는 이제 기본 URL에 포함되지 않고 `default_query`을 통해 전달되므로 SDK는 URL 조인 중에 매개변수를 손상시킬 수 없습니다.
**마법사에 "자동 감지가 불완전합니다."라고 표시됩니다.**
엔드포인트는 `/models` 프로브와 Anthropic Messages 프로브를 모두 거부했습니다. 이는 방화벽 뒤에 있거나 IP 허용 목록이 있는 개인 끝점의 경우 정상적인 현상입니다. 수동 API 모드 선택으로 돌아가서 배포 이름을 입력하세요. 모든 것이 여전히 작동하지만 Hermes는 선택기를 미리 채울 수 없습니다.
**잘못된 운송수단이 선택되었습니다.**
`hermes model`을 다시 실행하면 마법사가 다시 검색합니다. 프로브가 여전히 잘못된 모드를 선택하는 경우 `config.yaml`을 직접 편집할 수 있습니다.
```yaml
model:
provider: azure-foundry
api_mode: anthropic_messages # or chat_completions
관련
- 환경변수
- 구성
- AWS Bedrock — 또 다른 주요 클라우드 제공업체 통합