> For the complete documentation index, see [llms.txt](https://help.genesis.autify.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.genesis.autify.com/features-ko/settings/connection-settings/ai-provider-settings.md).

# AI 프로바이더 설정

이 문서에서는 AI 프로바이더 기능을 설명합니다.

AI 프로바이더 설정에는 **매니지드 AI 프로바이더**와 \*\*BYOK(Bring Your Own Key)\*\*의 2가지 모드가 있습니다. 계약 시에 둘 중 한 가지 모드를 선택하여 이용합니다.

BYOK 모드를 사용하면 조직이 보유한 AI 프로바이더의 API 키를 Autify Genesis에 등록하여, 채팅 생성이나 지식 베이스 검색 등의 AI 기능에 이용할 수 있습니다.

{% hint style="info" %}
계약 후에 모드 변경을 원하는 경우, 당사 담당자 또는 고객 지원에 문의하십시오.
{% endhint %}

## 사전 조건

* AI 프로바이더의 인증 정보를 생성·편집·삭제할 수 있는 사람은 **조직 소유자**뿐입니다. 관리자·구성원은 설정 열람만 가능합니다.
* **BYOK 모드**를 신규로 활성화하려면 사전에 <support@autify.com>으로 문의하십시오. 활성화 후, 본 문서의 절차에 따라 프로바이더를 관리할 수 있게 됩니다.

## 매니지드 AI 프로바이더

### 프로바이더 제한

조직에서 사용 가능한 AI 프로바이더를 관리합니다. 각 프로바이더의 토글로 개별적으로 활성화·비활성화를 전환할 수 있습니다.

프로바이더를 비활성화하면 해당 모델은 워크플로와 채팅에서 제외됩니다.

<figure><img src="/files/qm3HyUNmltNbqrOrJyIw" alt="프로바이더 제한 스크린샷"><figcaption><p>프로바이더 제한</p></figcaption></figure>

## BYOK(Bring Your Own Key) 모드

### 채팅 프로바이더 설정하기

채팅 프로바이더란 채팅 생성 기능에서 사용하는 AI 프로바이더입니다. AI 기능을 이용하려면 최소 1개의 채팅 프로바이더를 설정하고 활성화해야 합니다.

1. **채팅 설정** 섹션에서 사용할 프로바이더(OpenAI, Azure OpenAI, Google Gemini)의 **설정**을 클릭하십시오.
2. 설정 대화 상자가 열리면 다음 정보를 입력하십시오.

| 필드               | 설명                |
| ---------------- | ----------------- |
| **API 키**        | 프로바이더에서 발급된 API 키 |
| **표시 이름 (선택사항)** | 관리용 임의의 이름        |

{% hint style="info" %}
**Azure OpenAI**를 사용하는 경우, **API 키**에 더해 **베이스 URL**을 입력합니다(예: `https://my-resource.openai.azure.com/openai/v1`, `https://my-resource.cognitiveservices.azure.com/openai/v1`)。 API 버전은 베이스 URL의 경로에 포함되며, 기본적으로 `v1`이 사용됩니다。

Azure OpenAI 채팅 설정에서는 **연결 테스트**를 실행하면 Genesis가 Azure 리소스에서 사용 가능한 배포를 감지하여 저장 전에 목록으로 보여줍니다。 배포를 하나도 감지하지 못하면 저장할 수 없습니다。 리소스와 지역을 확인하거나 \*\*배포 이름 재정의 (선택사항)\*\*를 추가한 뒤 다시 테스트하십시오。

Azure 측의 배포 이름이 모델 ID와 다른 경우, \*\*배포 이름 재정의 (선택사항)\*\*에 `모델=배포`를 쉼표로 구분하여 지정합니다(예: `gpt-5.2=my-gpt52-deploy, gpt-5.4=my-gpt54-deploy`)。 지정하지 않은 모델에서는 모델 ID가 그대로 배포 이름으로 사용됩니다。 \*\*배포 이름 재정의 (선택사항)\*\*과 임베딩용 **배포 이름**에는 Azure에서 설정한 실제 이름을 입력하십시오. 점(`.`)이 포함된 이름도 그대로 사용할 수 있습니다。

Genesis는 자동 채팅 제목 생성, 메모리 업데이트, 긴 워크플로에서의 컨텍스트 압축 등의 백그라운드 AI 호출에서도 조직에서 사용 가능한 모델을 사용합니다。
{% endhint %}

3. **연결 테스트**를 클릭하십시오.
   * **OpenAI**와 **Google Gemini**에서는 **연결 성공**이라고 표시되는지 확인하십시오.
   * **Azure OpenAI** 채팅 설정에서는 감지된 배포가 목록으로 표시되는지 확인하십시오.

{% hint style="warning" %}
연결 테스트가 성공할 때까지 **저장**은 클릭할 수 없습니다. 반드시 먼저 테스트를 실행하십시오.
{% endhint %}

4. 테스트가 성공하면 **저장**을 클릭하십시오.
5. 프로바이더 카드에 표시되는 토글을 켜서 프로바이더를 활성화하십시오.

여러 채팅 프로바이더를 등록할 수 있습니다. 각 프로바이더의 토글로 개별적으로 활성화·비활성화를 전환할 수 있습니다.

### Azure OpenAI 배포 새로 고침

나중에 Azure 쪽에서 배포를 추가하거나 제거한 경우, API 키를 다시 입력하지 않고 저장된 목록을 갱신할 수 있습니다.

1. 설정된 **Azure OpenAI** 채팅 프로바이더 카드에서 **배포 새로 고침**을 클릭하십시오.
2. 미리보기 대화 상자에서 감지된 배포를 확인하십시오.
3. **적용**을 클릭하여 저장된 배포 목록을 바꾸십시오.

Azure 리소스의 호스트 이름이나 경로도 바꾼 경우에는 먼저 **설정**에서 **베이스 URL**을 업데이트하고, **연결 테스트**를 다시 실행한 뒤 배포를 새로 고치십시오。

### 임베딩용 프로바이더 설정하기

임베딩용 프로바이더란 지식 베이스 구축(인덱싱)이나 검색에 사용하는 프로바이더입니다. 지식 베이스 기능을 이용하는 경우 설정이 필요합니다.

1. **임베딩 설정** 섹션에서 사용할 프로바이더의 **설정**을 클릭하십시오.
2. 채팅 프로바이더와 마찬가지로 **API 키**를 입력하십시오. Azure OpenAI를 사용하는 경우, **베이스 URL**에 더해 **배포 이름**에도 입력합니다. **배포 이름**에는 `text-embedding-3-small` 모델(1536 차원)의 정확한 Azure 배포 이름을 지정합니다. 저장한 값이 그대로 임베딩 요청에 사용되므로 Azure에 설정된 실제 이름을 입력하십시오.
3. **연결 테스트**를 실행하고, 테스트가 성공하면 **저장**을 클릭하십시오.
4. 등록된 프로바이더를 선택하십시오. 클릭하는 즉시 해당 프로바이더로 전환되고, 기존 지식 베이스의 재구성이 시작됩니다.

{% hint style="warning" %}
임베딩용 프로바이더를 전환하면 모든 지식 베이스가 재구성됩니다. 완료까지 몇 분 정도 걸릴 수 있습니다.
{% endhint %}

활성화할 수 있는 임베딩용 프로바이더는 동시에 1개뿐입니다.

### Other AI Providers

조직에서 **Other AI Providers**를 사용할 수 있다면, 같은 설정 화면에서 OpenAI 호환 엔드포인트도 연결할 수 있습니다. 감지된 모델은 채팅과 워크플로에서 사용할 수 있습니다.

1. **Other AI Providers**에서 **Add provider**를 클릭하십시오.
2. 이름, OpenAI 호환 **Base URL**, **API Key**를 입력하십시오.
3. **Test Connection**을 클릭하십시오. Genesis가 해당 엔드포인트에서 제공하는 모델을 감지합니다.
4. 감지된 모델을 확인한 뒤 **Save**를 클릭하십시오.
5. 프로바이더를 활성화하면, 해당 모델을 채팅과 워크플로에서 사용할 수 있습니다.

이후 엔드포인트에서 제공하는 모델이 바뀌면 프로바이더 카드의 **Refresh models**로 저장된 목록을 갱신할 수 있습니다. 이름이나 인증 정보를 바꾸려면 **Edit**, 삭제하려면 **Remove**를 사용하십시오.

### 프로바이더의 인증 정보 편집하기

등록된 프로바이더의 API 키나 표시 이름을 변경하는 경우, 다음 절차로 업데이트합니다.

1. 변경할 프로바이더 카드의 **편집**을 클릭하십시오.
2. 새 인증 정보를 입력하고 **연결 테스트**를 실행하십시오.
3. 테스트가 성공하면 **저장**을 클릭하십시오.

### 프로바이더의 인증 정보 취소하기

1. 취소할 프로바이더 카드의 **취소**를 클릭하십시오.
2. 확인 대화 상자가 표시되면 내용을 확인하고 **취소**를 클릭하십시오.

{% hint style="danger" %}
인증 정보를 취소하면 그 인증 정보를 사용하는 기능은 즉시 중단됩니다. 플랫폼이 관리하는 키로의 자동 폴백은 없습니다.
{% endhint %}

### 문제 해결

#### 채팅 프로바이더가 설정되지 않음

채팅 프로바이더가 하나도 활성화되어 있지 않은 경우, 설정 페이지에 빨간색 경고 메시지가 표시됩니다. 또한 설정 페이지 이외의 페이지를 열려고 하면 설정 대화 상자가 표시되어 조작이 차단됩니다.

| 상황                                                | 원인                            | 해결 방법                                    |
| ------------------------------------------------- | ----------------------------- | ---------------------------------------- |
| 경고 "AI 기능을 사용하려면 최소 하나의 채팅 프로바이더를 구성해야 합니다."가 표시됨 | 채팅 프로바이더가 미설정이거나 모두 비활성화되어 있음 | 채팅 프로바이더를 1개 이상 설정하고 토글을 켜서 활성화하십시오      |
| 설정 대화 상자가 표시되어 조작할 수 없음(소유자의 경우)                  | BYOK 모드에서 채팅 프로바이더가 미설정       | **AI 프로바이더 설정으로 이동**을 클릭하여 프로바이더를 설정하십시오 |
| 설정 대화 상자가 표시되어 조작할 수 없음(관리자·구성원의 경우)              | 채팅 프로바이더가 미설정                 | 조직 소유자에게 AI 프로바이더 설정을 요청하십시오             |

#### 연결 테스트가 실패함

| 상황                                      | 원인                                            | 해결 방법                                                                                      |
| --------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------ |
| "연결 테스트 실패"가 표시됨                        | API 키가 유효하지 않거나 만료됨                           | 프로바이더 관리 화면에서 유효한 API 키를 다시 발급하고 다시 입력하십시오                                                 |
| Azure OpenAI에서 연결 테스트가 실패함              | 베이스 URL(리소스·API 버전 부분) 또는 배포 설정 입력이 올바르지 않음   | Azure 포털에서 리소스 이름, 지역, 배포 설정을 확인한 후 베이스 URL과 필요한 배포 이름 재정의를 다시 입력하십시오                      |
| Azure OpenAI 연결 테스트 후에도 배포가 목록에 표시되지 않음 | 현재 리소스 또는 배포 설정으로는 Genesis가 지원되는 채팅 배포를 찾지 못함 | 리소스와 지역을 확인하십시오. 배포 이름이 모델 ID와 다른 경우 \*\*배포 이름 재정의 (선택사항)\*\*를 추가한 뒤 **연결 테스트**를 다시 실행하십시오 |

위 외에도 네트워크 설정(프록시, 방화벽), IP 제한, 각 프로바이더의 일시적인 장애 등으로 인해 연결 테스트가 실패하는 경우가 있습니다. 오류 메시지에 프로바이더로부터의 세부 내용이 표시되는 경우, 그 내용도 함께 확인하십시오.

#### 임베딩용 프로바이더가 선택되지 않음

등록된 임베딩용 프로바이더가 존재함에도 선택되지 않은 경우, 노란색 경고 메시지 "임베딩 프로바이더가 선택되지 않았습니다. 지식 베이스 기능이 작동하지 않습니다."가 표시됩니다. 어느 한 프로바이더를 선택하여 활성화하십시오.