자체 AI 제공자 사용

Archyl에는 아키텍처 발견, ADR 파싱, 채팅, 인사이트 및 관리형 에이전트를 위한 AI 기능이 포함됩니다. 기본적으로 이 모든 것은 Archyl이 관리하는 모델에서 실행됩니다. 컴플라이언스, 계약 또는 데이터 거주성 이유로 기존 AI 제공자 관계를 가진 조직은 자체 자격 증명을 사용하여 자체 제공자를 통해 모든 AI 요청을 라우팅할 수 있습니다.

BYO Provider가 활성화되면:

모든 AI 기능은 구성한 제공자를 통해 라우팅됩니다
Archyl 쿼터 적용(채팅 쿼리, AI 발견, 에이전트 실행)이 건너뛰어집니다 — 제공자가 토큰 사용량을 직접 청구합니다
기능별 모델 선택으로 모델을 혼합할 수 있습니다(예: 채팅용 Claude Sonnet, 발견용 Claude Opus)

이는 조직 수준 설정입니다. 조직 관리자만 구성할 수 있습니다.

지원되는 제공자

제공자	설명	기본 모델
OpenAI	`api.openai.com`의 직접 OpenAI API	`gpt-5.6-luna`
Anthropic	직접 Anthropic Messages API (Claude)	`claude-sonnet-4-6`
Google	Google Generative Language API (Gemini)	`gemini-2.0-flash`
AWS Bedrock	Bedrock Converse API — Anthropic Claude, Mistral, Llama, Titan, Cohere 포함	`anthropic.claude-sonnet-4-20250514-v1:0`
OpenAI 호환	OpenAI Chat Completions 형식을 사용하는 모든 엔드포인트 — Azure OpenAI, GitHub Models, OpenRouter, Mistral La Plateforme, Groq, Together AI, Fireworks, DeepInfra, vLLM, llama.cpp 등	(제공자별)

OpenAI 호환 어댑터는 긴 테일의 공급업체를 다루는 단일 구성입니다. 기본 URL과 API 키를 제공하면 Archyl이 OpenAI인 것처럼 엔드포인트와 통신합니다.

구성

1단계 — AI 탭 열기

조직 설정 → AI로 이동합니다. 탭은 관리자에게만 표시됩니다.

2단계 — 제공자 선택

다섯 개의 제공자 카드 중 하나를 선택합니다. 각 카드는 자체 자격 증명 요구 사항을 가집니다:

OpenAI / Anthropic / Google — API 키만
OpenAI 호환 — API 키 + 기본 URL (예: https://api.openrouter.ai/api/v1, https://api.mistral.ai/v1, https://models.github.ai/inference)
AWS Bedrock — <access_key_id>:<secret_access_key> 형식의 자격 증명 (STS 자격 증명용 선택적 :<session_token> 접미사), AWS 리전 추가 (예: us-east-1)

3단계 — 기능별 모델 구성 (선택사항)

각 AI 기능은 다른 모델을 사용할 수 있습니다. 모든 필드를 비워 두면 제공자의 기본값으로 돌아갑니다.

기능	설명
채팅	스트리밍 채팅 어시스턴트
발견	리포지토리 전체 AI 발견 — 안정적인 JSON 출력 필요
구조 분석	발견 1단계 (시스템 + 컨테이너)
관계 정제	발견 3단계 (컨테이너 간 링크)
ADR 파싱	ADR 마크다운에서 구조화된 필드 추출
파일 분석	파일별 세부 분석
문서 제목 생성	문서 제목 일괄 생성
인사이트	AI가 생성한 아키텍처 인사이트
관리형 에이전트	관리형 에이전트 실행에 사용되는 모델 (아래 "관리형 에이전트" 섹션 참조)

제공자가 게시한 정확한 모델 식별자를 사용하세요 (claude-opus-4-5, gpt-4o, mistral-large-latest, anthropic.claude-sonnet-4-20250514-v1:0 등). Archyl이 그대로 전달합니다.

4단계 — 연결 테스트

연결 테스트를 클릭하세요. Archyl이 자격 증명으로 구성된 제공자에 대해 최소 completion을 발행합니다. 녹색 체크 표시는 자격 증명이 작동함을 확인합니다. 오류는 제공자의 응답을 표시하여 저장하기 전에 구성을 수정할 수 있도록 합니다.

5단계 — 활성화 및 저장

이 조직에 대해 BYO 제공자 활성화를 체크하고 설정 저장을 클릭하세요. 조직의 누구로부터의 다음 AI 요청 — 채팅, 발견, 에이전트 실행, ADR 가져오기 — 은 당신의 제공자를 통해 라우팅됩니다.

쿼터 동작

BYO Provider가 비활성화된 경우 (기본값), AI 사용량은 구독의 월간 쿼터에 대해 카운트됩니다:

AI 발견 작업
채팅 쿼리
관리형 에이전트 실행

BYO Provider가 활성화된 경우, 세 개의 쿼터 모두 조직에 대해 우회됩니다. 사용된 토큰에 대해 제공자에게 직접 지불하며, Archyl은 더 이상 이러한 기능에 대한 속도 제한을 적용하지 않습니다. 시트 기반 구독은 다른 모든 것에 여전히 적용됩니다 (협업 기능, 팀 한도 등).

우회는 토글을 활성화하면 즉시 적용되고 비활성화하면 즉시 되돌려집니다.

보안

API 키는 플랫폼의 암호화 키로 AES-256-GCM을 사용하여 저장 시 암호화됩니다. API 응답에서 절대 반환되지 않습니다 — 저장되면 UI는 ••••••••와 "키 저장됨" 표시기를 표시하고, 키는 AI 요청이 이루어져야 할 때만 인프로세스에서 복호화됩니다.

기존 키를 교체하려면 새 값을 입력하고 저장하세요. 완전히 지우려면 구성 제거를 클릭하세요. 이는 항목을 삭제하고 조직을 플랫폼 관리 AI로 되돌립니다.

조직 관리자만 이러한 설정을 읽거나 수정할 수 있습니다. 멤버는 AI 기능이 투명하게 계속 작동하는 것을 봅니다 — 라우팅은 그들에게 보이지 않습니다.

관리형 에이전트

BYO Provider가 활성화되면 관리형 에이전트 실행은 전적으로 조직의 제공자에서 조직의 자격 증명으로 실행됩니다. Archyl 자체 모델이 대체 수단으로 사용되는 일은 없습니다.

제공자	관리형 에이전트	모델
Anthropic	지원	관리형 에이전트 모델, 미설정 시 `claude-sonnet-4-6`
AWS Bedrock	지원 (Anthropic Claude 모델)	관리형 에이전트 모델, 미설정 시 `anthropic.claude-sonnet-4-20250514-v1:0`. `eu.anthropic.claude-sonnet-4-5-20250929-v1:0` 같은 교차 리전 프로필도 사용할 수 있습니다
OpenAI	지원	관리형 에이전트 모델, 미설정 시 `gpt-5.6-luna`
OpenAI 호환	엔드포인트가 OpenAI Responses API를 구현하는 경우 지원	관리형 에이전트 모델 — 필수이며 기본값이 없습니다
Google	아직 지원되지 않음	—

제공자가 에이전트를 실행할 수 없거나 OpenAI 호환 엔드포인트에 모델이 설정되지 않은 경우, 선택하지 않은 모델로 실행되는 대신 명확한 메시지와 함께 실행 시작이 실패합니다.

문제 해결

"연결 테스트"가 401 / 403으로 실패합니다. 키가 주변 공백 없이 올바르게 붙여 넣어졌는지 다시 확인하세요. Bedrock의 경우 형식이 <access_key_id>:<secret_access_key> (콜론으로 구분)이며 리전이 AWS 계정에서 모델이 활성화된 리전과 일치하는지 확인하세요.

"baseUrl is required for openai_compatible provider". 기본 URL 필드는 OpenAI 호환 어댑터에 필수입니다. API의 루트를 가리켜야 합니다. 예: https://api.openrouter.ai/api/v1 — 끝에 /chat/completions 없이.

발견이 잘못된 JSON을 반환합니다. Archyl의 프롬프트는 OpenAI의 엄격한 JSON 모드에 맞게 조정되었습니다. 일부 제공자/모델은 마크다운 코드 펜스 안에 JSON을 반환하거나 주석을 추가합니다. 발견, 구조 분석 및 관계 정제 기능에 대해 특별히 강력한 JSON 모드 안정성을 가진 모델 (예: gpt-4o, claude-sonnet-4-6, gemini-2.0-flash)로 전환하세요 — 채팅 및 기타 기능은 더 관대합니다.

채팅은 작동하지만 Bedrock에서 발견이 실패합니다. 일부 Bedrock 모델 ID에는 Provisioned Throughput 또는 특정 교차 리전 추론 프로필이 필요합니다. Bedrock 콘솔에서 계정에 대해 모델이 활성화되어 있고 선택한 리전이 모델의 가용성과 일치하는지 확인하세요.