> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Open WebUI에서 Ace Data Cloud 사용하기

> Platform API guide - Ace Data Cloud

[Open WebUI](https://openwebui.com/)(구 Ollama WebUI)는 다중 사용자, 지식 베이스, RAG 및 프라이빗 배포를 지원하는 오픈 소스 AI 클라이언트입니다. 사용자 지정 OpenAI 호환 엔드포인트를 지원하므로 Ace Data Cloud에 연동할 수 있습니다. 이 글에서는 구성 절차를 소개합니다.

## 신청 절차

Open WebUI에서 Ace Data Cloud에 연동하려면 먼저 [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console/applications)로 이동하여 API Token을 받아 예비용으로 보관합니다.

![Ace Data Cloud API Key 가져오기](https://cdn.acedata.cloud/dvc3cg.jpg)

아직 로그인하거나 등록하지 않았다면 로그인 페이지로 자동 이동하여 등록 및 로그인을 안내하며, 로그인 및 등록 후 현재 페이지로 자동 돌아옵니다.

최초 신청 시 무료 할당량이 제공되며, Ace Data Cloud의 모델 서비스를 무료로 체험할 수 있습니다.

## Ace Data Cloud 배포 및 구성

Open WebUI는 환경 변수를 통해 OpenAI 호환 엔드포인트에 연동하며, Docker 한 줄 명령으로 배포할 수 있습니다(`{token}`을 자신의 Token으로 교체):

```bash theme={null}
docker run -d \
  --name open-webui \
  -p 3000:8080 \
  -e WEBUI_SECRET_KEY=$(openssl rand -base64 32) \
  -e OPENAI_API_BASE_URL=https://api.acedata.cloud/v1 \
  -e OPENAI_API_KEY={token} \
  -v open-webui:/app/backend/data \
  ghcr.io/open-webui/open-webui:main
```

| 환경 변수 | 역할 |
| - | - |
| `OPENAI_API_BASE_URL` | Ace Data Cloud 엔드포인트, **반드시 `/v1`로 끝나야 함** |
| `OPENAI_API_KEY` | 자신의 Token |
| `WEBUI_SECRET_KEY` | session 암호화 키, 자동 생성 |
| `-v open-webui:/app/backend/data` | 대화 / 사용자 데이터 영속화 |

`http://서버IP:3000`을 열면 첫 번째로 등록한 계정이 자동으로 관리자가 됩니다. Base URL의 경로 규칙에 유의하세요:

| OPENAI\_API\_BASE\_URL | 실제 요청 | 결과 |
| - | - | - |
| `https://api.acedata.cloud/v1` | `https://api.acedata.cloud/v1/chat/completions` | 올바름 |
| `https://api.acedata.cloud/openai` | `https://api.acedata.cloud/openai/chat/completions` | 사용 가능 |
| `https://api.acedata.cloud/openai/v1` | `https://api.acedata.cloud/openai/v1/chat/completions` | 404(`/openai` 아래에 `/v1` 없음) |

로그인 후 **Admin Panel → Settings → Connections**로 이동하여 「Verify Connection」을 클릭해 검증합니다. **Settings → Models**에서 자주 사용하는 모델을 필터링하고 Pin할 수 있습니다.

> 환경 변수를 사용하는 것 외에도 Open WebUI는 인터페이스에서 직접 연결을 추가하는 것을 지원합니다: **Admin Settings → Connections**로 이동하여 ➕를 클릭하고 URL(`https://api.acedata.cloud/v1`) 및 API Key를 입력하면 됩니다. Open WebUI는 자동으로 `/models`를 호출하여 모델 목록을 가져옵니다. 자세한 내용은 공식 문서 [Starting With OpenAI-Compatible Servers](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)를 참조하세요.

![Open WebUI Ace Data Cloud Connection 구성 화면](https://cdn.acedata.cloud/f366abfd935d.png)

> `MODEL_ID`는 선택 가능한 allow list를 보여 주기 위한 용도로만 사용됩니다. 비워 두면 `/models`가 반환한 모든 모델이 표시됩니다.

## 모델 선택

모델 카탈로그는 지속적으로 업데이트됩니다. 클라이언트가 자동으로 불러오는 모델 목록을 우선 사용하세요. 수동으로 입력해야 하는 경우 먼저 `GET https://api.acedata.cloud/v1/models`를 요청하여 현재 모델 ID를 가져온 후, 클라이언트가 지원하는 컨텍스트, 이미지 및 도구 호출 기능에 따라 선택하세요.

## 연동 검증

문제가 Open WebUI에 있는지 네트워크에 있는지 확실하지 않다면, 먼저 curl로 엔드포인트를 직접 검증할 수 있습니다(`{token}`을 자신의 Token으로 교체):

```bash theme={null}
curl -X POST 'https://api.acedata.cloud/v1/chat/completions' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "ping"}]
  }'
```

OpenAI 호환 `chat.completion` 객체가 반환되면 Token과 엔드포인트가 모두 준비되었음을 의미합니다. `HTTP 403 used_up`이 반환되면 Token은 유효하지만 잔액이 부족하다는 의미이므로 [콘솔](https://platform.acedata.cloud/console/applications)에서 충전하면 됩니다.

## 고급: 지식 베이스 및 다중 사용자

Open WebUI의 지식 베이스(RAG)는 기본적으로 ChromaDB를 사용하여 벡터를 저장하며, 임베딩 모델로 `text-embedding-3-large`(Ace Data Cloud를 통해)를 지정할 수 있습니다. 문서 원문은 자신의 서버에만 존재하며, 일치한 조각만 모델로 전송됩니다. **Admin Panel → Users**에서 사용자 역할(Pending / User / Admin)을 관리할 수 있습니다. 「Default User Role」을 `pending`으로 설정하는 것이 좋으며, 새 사용자는 검토 후에만 사용할 수 있어 외부인이 임의로 등록하여 할당량을 소모하는 것을 방지할 수 있습니다. nginx 리버스 프록시를 사용하는 경우 `proxy_buffering off;` 및 `client_max_body_size 100M;`를 추가하세요.

## 자주 묻는 질문

### Connection error / 404가 표시됨

일반적으로 `OPENAI_API_BASE_URL`을 `.../openai/v1`로 작성했거나 `/v1`을 누락한 경우입니다. `https://api.acedata.cloud/v1`로 변경하세요.

### 문서 업로드 후 대화할 수 없음

Admin Panel의 RAG 설정에서 임베딩 모델을 `text-embedding-3-large`(OpenAI provider)로 선택하세요.

### 컨테이너 재시작 후 데이터가 사라짐

시작할 때 데이터 볼륨 `-v open-webui:/app/backend/data`를 마운트해야 합니다.

## 더 알아보기

* [Open WebUI 공식 사이트](https://openwebui.com/) ｜ [Open WebUI GitHub](https://github.com/open-webui/open-webui) ｜ [빠른 시작 문서](https://docs.openwebui.com/getting-started/quick-start)
* [Open WebUI의 OpenAI 호환 엔드포인트 연동 공식 문서](https://docs.openwebui.com/getting-started/quick-start/connect-a-provider/starting-with-openai-compatible)
* [Ace Data Cloud OpenAI Chat Completions API 문서](https://platform.acedata.cloud/documents/openai-chat-completions)
* [Ace Data Cloud 서비스 목록](https://platform.acedata.cloud/documents)
* [Ace Data Cloud 콘솔](https://platform.acedata.cloud/console)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.