제공자 추가
Hermes는 이미 사용자 지정 제공자 경로를 통해 모든 OpenAI 호환 엔드포인트와 통신할 수 있습니다. 해당 서비스에 대해 최고 수준의 UX를 원하지 않는 한 기본 제공 제공자를 추가하지 마세요.
- 제공자별 인증 또는 토큰 새로 고침
- 엄선된 모델 카탈로그
- 설정 /
hermes model메뉴 항목 provider:model구문에 대한 제공자 별칭- 어댑터가 필요한 비OpenAI API 형태
제공자가 "또 다른 OpenAI 호환 기본 URL 및 API 키"인 경우 명명된 사용자 지정 제공자로 충분할 수 있습니다.
정신 모델
기본 제공 제공자는 여러 계층에 걸쳐 정렬되어야 합니다.
hermes_cli/auth.py은 자격 증명을 찾는 방법을 결정합니다.hermes_cli/runtime_provider.py은 이를 런타임 데이터로 변환합니다.providerapi_modebase_urlapi_keysource
run_agent.py은api_mode을 사용하여 요청이 작성되고 전송되는 방법을 결정합니다.hermes_cli/models.py및hermes_cli/main.py을 사용하면 제공자가 CLI에 표시됩니다. (hermes_cli/setup.py은main.py에 자동으로 위임됩니다. 거기에서는 변경할 필요가 없습니다.)agent/auxiliary_client.py및agent/model_metadata.py은 부가 작업과 토큰 예산 책정이 작동하도록 유지합니다.
중요한 추상화는 api_mode입니다.
- 대부분의 제공자는
chat_completions을 사용합니다. - 코덱스는
codex_responses을 사용합니다. - Anthropic은
anthropic_messages을 사용합니다. - 새로운 비OpenAI 프로토콜은 일반적으로 새로운 어댑터와 새로운
api_mode분기를 추가하는 것을 의미합니다.
먼저 구현 경로를 선택하세요.
경로 A — OpenAI 호환 제공자
제공자가 표준 Chat Completions 스타일 요청을 수락할 때 이를 사용합니다.
일반적인 작업:
- 인증 메타데이터 추가
- 모델 카탈로그/별칭 추가
- 런타임 해상도 추가
- CLI 메뉴 연결 추가
- 보조 모델 기본값 추가
- 테스트 및 사용자 문서 추가
일반적으로 새 어댑터나 새 api_mode은 필요하지 않습니다.
경로 B - 기본 제공자
제공자가 OpenAI Chat Completions처럼 작동하지 않을 때 이를 사용합니다.
오늘 트리의 예:
codex_responsesanthropic_messages
이 경로에는 경로 A의 모든 내용과 다음이 포함됩니다.
agent/의 제공자 어댑터run_agent.py요청 작성, 디스패치, 사용량 추출, 인터럽트 처리 및 응답 정규화를 위한 분기- 어댑터 테스트
파일 체크리스트
모든 내장 제공자에 필수
hermes_cli/auth.pyhermes_cli/models.pyhermes_cli/runtime_provider.pyhermes_cli/main.pyagent/auxiliary_client.pyagent/model_metadata.py- 테스트
website/docs/아래의 사용자 대상 문서
hermes_cli/setup.py에는 변경이 필요하지 않습니다. 설정 마법사는 제공자/모델 선택을 main.py의 select_provider_and_model()에 위임합니다. 여기에 추가된 모든 제공자는 자동으로 hermes setup에서 사용할 수 있습니다.
네이티브/비OpenAI 제공업체에 대한 추가 정보
agent/<provider>_adapter.pyrun_agent.pypyproject.toml제공자 SDK가 필요한 경우
빠른 경로: 간단한 API 키 제공자
제공자가 단일 API 키로 인증하는 OpenAI 호환 엔드포인트인 경우 auth.py, runtime_provider.py, main.py 또는 아래 전체 체크리스트에 있는 다른 파일을 터치할 필요가 없습니다.
필요한 것은 다음과 같습니다.
- 다음을 포함하는
plugins/model-providers/<your-provider>/아래의 플러그인 디렉터리:__init__.py— 모듈 수준에서register_provider(profile)을 호출합니다.plugin.yaml— 매니페스트(이름, 종류: 모델 제공자, 버전, 설명)
- 그게 다야.
get_provider_profile()또는list_providers()을 처음 호출하면 제공자 플러그인이 자동으로 로드됩니다. 번들 플러그인(이 저장소)과$HERMES_HOME/plugins/model-providers/의 사용자 플러그인이 모두 선택됩니다.
플러그인을 추가하고 register_provider()을 호출하면 다음 연결이 자동으로 연결됩니다.
PROVIDER_REGISTRY항목(auth.py)(자격 증명 확인, env-var 조회)api_mode이(가)chat_completions로 설정되었습니다.base_url은 구성 또는 선언된 env var에서 제공됩니다.env_varsAPI 키의 우선순위로 확인됨fallback_models목록이 제공자에 등록되었습니다.--providerCLI 플래그는 제공자 ID를 허용합니다.hermes model메뉴에는 제공자가 포함됩니다.hermes setup마법사가main.py에 자동으로 위임합니다.provider:model별칭 구문이 작동합니다.- 런타임 확인자는 올바른
base_url및api_key을 반환합니다. HERMES_INFERENCE_PROVIDERenv-var 재정의는 제공자 ID를 허용합니다.- 대체 모델 활성화는 제공자로 깔끔하게 전환할 수 있습니다.
$HERMES_HOME/plugins/model-providers/<name>/의 사용자 플러그인은 동일한 이름의 번들 플러그인(register_provider()의 최종 작성자 승리)을 재정의합니다. 따라서 제3자가 리포지토리를 편집하지 않고도 내장 프로필을 원숭이 패치하거나 교체할 수 있습니다.
템플릿으로 plugins/model-providers/nvidia/ 또는 plugins/model-providers/gmi/을 참조하고, 필드 참조, 후크 관용구, 엔드투엔드 예시는 전체 모델 제공자 플러그인 가이드를 참조하세요.
전체 경로: OAuth 및 복잡한 제공자
사용자의 제공자가 다음 중 하나를 필요로 하는 경우 아래 전체 체크리스트를 사용하세요.
- OAuth 또는 토큰 새로 고침(Nous Portal, Codex, Google Gemini, Qwen Portal, Copilot)
- 새로운 어댑터가 필요한 비OpenAI API 형태(Anthropic Messages, Codex Responses)
- 맞춤형 엔드포인트 탐지 또는 다중 지역 조사(z.ai, Kimi)
- 선별된 정적 모델 카탈로그 또는 실시간
/models가져오기 - 맞춤형 인증 흐름이 포함된 제공업체별
hermes model메뉴 항목
1단계: 정식 제공자 ID 하나 선택
단일 제공자 ID를 선택하고 어디에서나 사용하세요.
저장소의 예:
openai-codexkimi-codingminimax-cn
동일한 ID가 다음 위치에 표시되어야 합니다.
PROVIDER_REGISTRY(hermes_cli/auth.py)_PROVIDER_LABELS(hermes_cli/models.py)_PROVIDER_ALIASES(hermes_cli/auth.py및hermes_cli/models.py모두)- CLI
--providerhermes_cli/main.py의 선택 사항 - 설정/모델 선택 분기
- 보조 모델 기본값
- 테스트
해당 파일 간에 ID가 다르면 제공자는 반쯤 연결된 것처럼 느낄 것입니다. /model, 설정 또는 런타임 확인이 자동으로 누락되는 동안 인증이 작동할 수 있습니다.
2단계: hermes_cli/auth.py에 인증 메타데이터 추가
API 키 제공자의 경우 다음을 사용하여 ProviderConfig 항목을 PROVIDER_REGISTRY에 추가합니다.
idnameauth_type="api_key"inference_base_urlapi_key_env_vars- 선택사항
base_url_env_var
또한 _PROVIDER_ALIASES에 별칭을 추가합니다.
기존 제공자를 템플릿으로 사용합니다.
- 간단한 API 키 경로: Z.AI, MiniMax
- 엔드포인트 감지 기능이 있는 API 키 경로: Kimi, Z.AI
- 기본 토큰 해결: Anthropic
- OAuth / 인증 저장소 경로: Nous, OpenAI Codex
여기에 대답할 질문:
- Hermes는 어떤 환경 변수를 확인해야 하며, 어떤 우선순위로 확인해야 합니까?
- 제공자에게 기본 URL 재정의가 필요합니까?
- 엔드포인트 조사 또는 토큰 새로 고침이 필요합니까?
- 자격 증명이 누락된 경우 인증 오류는 무엇을 말해야 합니까?
제공자에게 "API 키 조회" 이상의 기능이 필요한 경우 관련 없는 분기에 논리를 삽입하는 대신 전용 자격 증명 확인자를 추가하세요.
3단계: hermes_cli/models.py에 모델 카탈로그 및 별칭 추가
제공자가 메뉴 및 provider:model 구문에서 작동하도록 제공자 카탈로그를 업데이트합니다.
일반적인 편집:
_PROVIDER_MODELS_PROVIDER_LABELS_PROVIDER_ALIASESlist_available_providers()내의 제공자 표시 순서provider_model_ids()제공자가 라이브/models가져오기를 지원하는 경우
제공자가 실시간 모델 목록을 공개하는 경우 먼저 이를 선호하고 _PROVIDER_MODELS을 정적 대체 항목으로 유지하세요.
이 파일은 다음과 같은 입력을 수행하는 역할도 합니다.
anthropic:claude-sonnet-4-6
kimi:model-name
여기에 별칭이 누락된 경우 제공자는 올바르게 인증할 수 있지만 여전히 /model 구문 분석에 실패합니다.
4단계: hermes_cli/runtime_provider.py의 런타임 데이터 확인
resolve_runtime_provider()은 CLI, 게이트웨이, cron, ACP 및 도우미 클라이언트에서 사용하는 공유 경로입니다.
최소한 다음을 포함하는 사전을 반환하는 분기를 추가하세요.
{
"provider": "your-provider",
"api_mode": "chat_completions", # or your native mode
"base_url": "https://...",
"api_key": "...",
"source": "env|portal|auth-store|explicit",
"requested_provider": requested_provider,
}
제공자가 OpenAI와 호환되는 경우 api_mode은 일반적으로 chat_completions을 유지해야 합니다.
API 키 우선순위에 주의하세요. Hermes에는 관련 없는 엔드포인트에 OpenRouter 키가 유출되는 것을 방지하는 논리가 이미 포함되어 있습니다. 새로운 제공자는 어떤 키가 어떤 기본 URL로 이동하는지에 대해 똑같이 명시적이어야 합니다.
5단계: hermes_cli/main.py에 CLI 연결
제공자는 대화형 hermes model 흐름에 표시될 때까지 검색할 수 없습니다.
hermes_cli/main.py에서 다음을 업데이트하세요.
provider_labels사전providers목록(select_provider_and_model())- 제공자 파견(
if selected_provider ==...) --provider인수 선택- 제공자가 해당 흐름을 지원하는 경우 로그인/로그아웃 선택
_model_flow_<provider>()함수 또는 적합하다면_model_flow_api_key_provider()재사용
hermes_cli/setup.py은 변경할 필요가 없습니다. main.py에서 select_provider_and_model()을 호출하므로 새 제공자가 hermes model 및 hermes setup에 자동으로 나타납니다.
6단계: 보조 통화 작동 유지
여기서는 두 가지 파일이 중요합니다.
agent/auxiliary_client.py
직접 API 키 제공자인 경우 _API_KEY_PROVIDER_AUX_MODELS에 저렴하고 빠른 기본 보조 모델을 추가하세요.
보조 작업에는 다음과 같은 것들이 포함됩니다.
- 비전 요약
- 웹 추출 요약
- 컨텍스트 압축 요약
- 세션 검색 요약
- 메모리 플러시
제공자가 적절한 보조 기본값을 갖고 있지 않으면 부차 작업이 잘못 수행되거나 예기치 않게 값비싼 기본 모델을 사용할 수 있습니다.
agent/model_metadata.py
토큰 예산 책정, 압축 임계값 및 제한이 제대로 유지되도록 제공자 모델에 대한 컨텍스트 길이를 추가합니다.
7단계: 제공자가 기본 제공자인 경우 어댑터 및 run_agent.py 지원을 추가합니다.
제공자가 일반 Chat Completions가 아닌 경우 agent/<provider>_adapter.py에서 제공자별 논리를 격리합니다.
run_agent.py을 오케스트레이션에 집중하세요. 파일 전체에서 인라인으로 직접 빌드한 제공자 페이로드가 아닌 어댑터 도우미를 호출해야 합니다.
기본 제공자는 일반적으로 다음 장소에서 작업이 필요합니다.
새 어댑터 파일
일반적인 책임:
- SDK/HTTP 클라이언트 빌드
- 토큰 해결
- OpenAI 스타일 대화 메시지를 제공자의 요청 형식으로 변환
- 필요한 경우 도구 스키마 변환
- 제공자 응답을
run_agent.py이 예상하는 것으로 다시 정규화합니다. - 사용량 및 종료 이유 데이터 추출
run_agent.py
api_mode을 검색하고 모든 전환점을 감사하세요. 최소한 다음을 확인하세요.
__init__은 새로운api_mode을 선택합니다.- 제공자를 위한 클라이언트 구축 작업
_build_api_kwargs()은 요청 형식을 지정하는 방법을 알고 있습니다._interruptible_api_call()은 올바른 클라이언트 호출로 전달됩니다.- 인터럽트/클라이언트 재구축 경로 작동
- 응답 유효성 검사는 제공자의 형태를 받아들입니다.
- 종료 이유 추출이 정확함
- 토큰 사용량 추출이 정확함
- fallback-model 활성화는 새 제공자로 깔끔하게 전환할 수 있습니다.
- 요약 생성 및 메모리 플러시 경로는 여전히 작동합니다.
또한 self.client.에 대해 run_agent.py을 검색하세요. 표준 OpenAI 클라이언트가 존재한다고 가정하는 모든 코드 경로는 기본 제공자가 다른 클라이언트 개체 또는 self.client = None을 사용하는 경우 중단될 수 있습니다.
프롬프트 캐싱 및 제공자별 요청 필드
프롬프트 캐싱 및 제공자별 손잡이는 회사용자기 쉽습니다.
이미 트리에 있는 예:
- Anthropic에는 기본 프롬프트 캐싱 경로가 있습니다.
- OpenRouter는 제공자 라우팅 필드를 얻습니다.
- 모든 제공자가 모든 요청 측 옵션을 받아야 하는 것은 아닙니다.
기본 제공자를 추가할 때 Hermes가 제공자가 실제로 이해하는 필드만 보내는지 다시 확인하세요.
8단계: 테스트
최소한 제공자 배선을 보호하는 테스트를 터치하세요.
일반적인 장소:
tests/test_runtime_provider_resolution.pytests/test_cli_provider_resolution.pytests/test_cli_model_command.pytests/test_setup_model_selection.pytests/test_provider_parity.pytests/test_run_agent.py- 기본 제공자의 경우
tests/test_<provider>_adapter.py
문서 전용 예제의 경우 정확한 파일 세트가 다를 수 있습니다. 요점은 다음을 다루는 것입니다.
- 인증 해결
- CLI 메뉴/제공자 선택
- 런타임 제공자 확인
- 에이전트 실행 경로
- 제공자:모델 구문 분석
- 모든 어댑터별 메시지 변환
xdist를 비활성화한 상태에서 테스트를 실행합니다:
source venv/bin/activate
python -m pytest tests/test_runtime_provider_resolution.py tests/test_cli_provider_resolution.py tests/test_cli_model_command.py tests/test_setup_model_selection.py -n0 -q
더 자세한 변경을 위해서는 푸시하기 전에 전체 제품군을 실행하세요.
source venv/bin/activate
python -m pytest tests/ -n0 -q
9단계: 실시간 검증
테스트 후에는 실제 스모크 테스트를 실행해 보세요.
source venv/bin/activate
python -m hermes_cli.main chat -q "Say hello" --provider your-provider --model your-model
메뉴를 변경한 경우 대화형 흐름도 테스트하세요.
source venv/bin/activate
python -m hermes_cli.main model
python -m hermes_cli.main setup
기본 제공자의 경우 일반 텍스트 응답뿐만 아니라 하나 이상의 도구 호출도 확인하세요.
10단계: 사용자에게 공개되는 문서 업데이트
제공자가 최고 수준의 옵션으로 배송될 예정이라면 사용자 문서도 업데이트하세요.
website/docs/getting-started/quickstart.mdwebsite/docs/user-guide/configuration.mdwebsite/docs/reference/environment-variables.md
개발자는 제공자를 완벽하게 연결할 수 있지만 여전히 사용자는 필요한 환경 변수 또는 설정 흐름을 찾을 수 없습니다.
OpenAI 호환 제공자 체크리스트
제공자가 표준 Chat Completions인 경우 이를 사용하세요.
ProviderConfig이hermes_cli/auth.py에 추가되었습니다.hermes_cli/auth.py및hermes_cli/models.py에 추가된 별칭hermes_cli/models.py에 모델 카탈로그가 추가되었습니다.hermes_cli/runtime_provider.py에 런타임 브랜치가 추가되었습니다.hermes_cli/main.py에 CLI 연결이 추가되었습니다(setup.py가 자동으로 상속됨).agent/auxiliary_client.py에 보조 모델이 추가되었습니다.agent/model_metadata.py에 추가된 컨텍스트 길이- 런타임/CLI 테스트 업데이트됨
- 사용자 문서가 업데이트되었습니다.
네이티브 제공업체 체크리스트
제공자에게 새 프로토콜 경로가 필요할 때 이를 사용합니다.
- OpenAI 호환 체크리스트의 모든 것
agent/<provider>_adapter.py에 추가된 어댑터- 새로운
api_mode은run_agent.py에서 지원됩니다. - 인터럽트/재구축 경로가 작동합니다.
- 사용 및 종료 이유 추출 작업
- 대체 경로가 작동합니다.
- 어댑터 테스트가 추가되었습니다.
- 실시간 연기 테스트 통과
일반적인 함정
1. 인증에는 제공자를 추가하지만 모델 구문 분석에는 추가하지 않음
이렇게 하면 /model 및 provider:model 입력이 실패하는 동안 자격 증명이 올바르게 확인됩니다.
2. config["model"]이 문자열이나 사전일 수 있다는 점을 잊어버림
많은 제공자 선택 코드는 두 형식을 모두 정규화해야 합니다.
3. 내장 제공자가 필요하다고 가정
서비스가 OpenAI와만 호환되는 경우 맞춤형 제공자는 더 적은 유지 관리로 이미 사용자 문제를 해결할 수 있습니다.
4. 보조 경로를 잊어버림
보조 라우팅이 업데이트되지 않았기 때문에 요약, 메모리 플러시 또는 비전 도우미가 실패하더라도 기본 채팅 경로는 작동할 수 있습니다.
5. run_agent.py에 숨어 있는 기본 제공자 지점
api_mode 및 self.client.을 검색하세요. 명백한 요청 경로가 유일한 경로라고 가정하지 마십시오.
6. OpenRouter 전용 노브를 다른 제공자에게 보내기
제공자 라우팅과 같은 필드는 이를 지원하는 제공자에만 속합니다.
7. hermes model은 업데이트하지만 hermes setup은 업데이트하지 않습니다.
두 흐름 모두 제공자에 대해 알아야 합니다.
구현하는 동안 좋은 검색 대상
제공자가 접촉하는 모든 장소를 찾고 있다면 다음 기호를 검색하세요.
PROVIDER_REGISTRY_PROVIDER_ALIASES_PROVIDER_MODELSresolve_runtime_provider_model_flow_select_provider_and_modelapi_mode_API_KEY_PROVIDER_AUX_MODELSself.client.