> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI 통합

> AI 채팅, LaTeX 오류 제안, 사용자 접근, 할당량 및 선택적 검색 서비스를 구성합니다.

> [!NOTE]
>
> 이 기능은 [ayaka-notes/ayakaleaf-pro](https://github.com/ayaka-notes/ayakaleaf-pro)에서 제공하며 v6.3.0부터 사용할 수 있습니다. 문제가 발생하면 언제든지 피드백을 보내주세요.

## AI 도우미와 LaTeX 오류 도우미

Ayakaleaf Pro는 두 가지 방식으로 편집기에 AI 기능을 제공합니다.

* AI 도우미는 프로젝트 문서와 현재 선택 영역을 컨텍스트로 사용하여 질문에 답하고, 검토할 수 있는 편집 제안을 제공합니다.
* 오류 도우미는 LaTeX 컴파일 오류를 선택하면 해당 오류에 맞춘 수정안을 제안합니다.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### Toolkit 구성

Toolkit 배포의 `config/variables.env`에 다음을 추가하고, 예시 URL, 키, 모델을 사용 중인 공급자의 값으로 바꾸세요.

```dotenv theme={null}
AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID
```

실제 API 키는 배포 환경 파일에 보관하고 버전 관리에 포함하지 마세요. 위 값은 자리 표시자일 뿐 실제로 작동하는 자격 증명이 아닙니다.

> [!NOTE]
>
> AI 제안의 품질은 선택한 모델에 따라 달라집니다. 이미 Codex 또는 ChatGPT 구독이 있다면 [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI)의 OpenAI 호환 엔드포인트를 통해 연결할 수 있습니다.

`AI_BASE_URL`은 OpenAI 호환 API의 기본 URL이며, 필요한 경우 공급자의 버전 접두사를 포함합니다. 내부적으로 `/chat/completions`를 덧붙이므로 직접 추가하지 마세요. 게이트웨이와 모델은 스트리밍 채팅 완성(chat completions)과 함수 도구(function tools)를 지원해야 합니다. 두 기능 모두 문서 컨텍스트를 이 게이트웨이로 전송하며, 이미지와 PDF를 지원하는 모델을 사용하는 경우 채팅에서 업로드한 이미지와 PDF 파일도 전송할 수 있습니다.

Toolkit은 `config/variables.env`를 애플리케이션 컨테이너로 전달합니다. 여기에 표시된 변수 이름을 그대로 사용하고 `OVERLEAF_` 접두사를 붙이지 마세요. 이 변수를 변경한 후에는 Toolkit 디렉터리에서 애플리케이션 컨테이너를 다시 생성하세요.

```sh theme={null}
bin/up -d
```

### 게이트웨이 설정

| 변수 | 기본값 | 용도 |
| - | - | - |
| `AI_ENABLED` | `false` | 인스턴스에서 채팅과 오류 제안을 활성화하려면 정확히 `true`로 설정합니다. 설정하지 않거나 다른 값이면 비활성 상태로 유지됩니다. 작동하는 게이트웨이 구성도 필요합니다. |
| `AI_BASE_URL` | 없음; 필수 | OpenAI 호환 API 기본 URL입니다. |
| `AI_API_KEY` | 없음; 필수 | 서버가 사용하는 해당 게이트웨이의 API 키입니다. |
| `AI_MODEL` | 없음; 필수 | 기본 채팅 구성과 LaTeX 오류 제안에 사용되는 텍스트 모델입니다. |
| `AI_IMAGE_MODEL` | 설정 안 됨 | 동일한 게이트웨이와 동일한 API 키를 사용하는 선택적 이미지 처리 가능 모델입니다. |
| `AI_PDF_MODEL` | 설정 안 됨 | 동일한 게이트웨이와 동일한 API 키를 사용하는, PDF 파일이 포함된 채팅용 선택적 모델입니다. v6.4.0부터 지원됩니다. |
| `AI_MAX_STEPS` | `20` | AI 채팅에서 사용자 메시지당 최대 도구 호출 횟수로, 자동 연속 호출을 포함합니다. 양의 정수를 사용하세요. |
| `AI_PROXY_URL` | 설정 안 됨 | AI 게이트웨이 호출에 사용할 선택적 HTTP 프록시 URL입니다. 웹 또는 문서 검색 클라이언트에는 적용되지 않습니다. |
| `AI_TOKEN_QUOTA` | `0` | 각 기간 동안 채팅과 오류 제안이 공유하는 사용자별 토큰 한도입니다. 설정하지 않거나 `0`이면 무제한이며, 한도를 두려면 양의 정수를 사용하세요. |
| `AI_TOKEN_QUOTA_PERIOD` | `month` | `month`는 매월 1일 00:00 UTC에 초기화되고, `week`는 매주 월요일 00:00 UTC에 초기화됩니다. 그 외의 값은 `month`로 처리됩니다. |

이미지 업로드를 사용하려면 `AI_IMAGE_MODEL`을 이미지 입력을 받고 채팅에서 사용하는 도구를 지원하는 모델로 설정하세요. 기록에 이미지 첨부 파일이 포함된 모든 채팅 요청은 이 모델을 사용하며, 해당 대화의 이후 메시지도 마찬가지입니다. 이 설정이 없으면 이미지 요청에 일반 채팅 모델이 사용되므로, 해당 모델 자체가 이미지를 지원해야 합니다. LaTeX 오류 제안은 계속 `AI_MODEL`을 사용합니다.

PDF 첨부 파일은 v6.4.0 이상부터 도입되었습니다. 사용자는 이미지와 마찬가지로 최대 2MB의 PDF 파일을 첨부할 수 있습니다. 채팅은 각 PDF 파일을 Chat Completions의 `file` 파트로 그대로 전송하므로, 게이트웨이와 모델이 PDF 입력을 지원해야 합니다. OpenAI의 비전 모델은 이를 지원하지만, vLLM과 같은 많은 자체 호스팅 게이트웨이는 이미지는 받아도 PDF 파일은 거부합니다. `AI_PDF_MODEL`을 PDF 파일을 읽을 수 있는 모델로 설정하세요. 기록에 PDF 파일이 포함된 모든 채팅은 이 모델을 사용하며, 해당 대화의 이후 메시지와 이미지도 마찬가지이므로 이미지도 지원하는 모델이어야 합니다. 이 설정이 없으면 PDF 채팅에 `AI_MODEL`이 사용됩니다. 모델이 PDF 파일을 거부하면 채팅은 사용자에게 관리자에게 `AI_PDF_MODEL` 설정을 요청하라고 안내합니다.

예를 들어 이미지 모델과 주간 AI 사용 한도를 활성화하려면 다음과 같이 설정합니다.

```dotenv theme={null}
AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week
```

### 사용자 접근 및 동의

인스턴스 가용성과 사용자 권한은 별개입니다. `AI_ENABLED`와 게이트웨이 구성은 인스턴스 가용성을 제어합니다. 로그인한 사용자는 기존 계정 검사도 통과해야 합니다. `aiFeatures.enabled`가 `false`가 아니어야 합니다. 이 기존 데이터베이스 필드는 채팅과 LaTeX 오류 제안을 모두 제어합니다. 이 값이 설정되어 있지 않으면 해당 사용자에게 AI 기능이 활성화됩니다.

`AI_TOKEN_QUOTA`는 허용된 각 사용자에게 동일하게 적용되는 한도이며, 현재 모듈은 계정별 개별 숫자 한도를 제공하지 않습니다.

관리자 사용자 목록에서 사용자를 선택하고 **Update account info → AI features**를 엽니다. **Enable AI features**는 계정 변경 사항을 저장할 때 `aiFeatures.enabled`를 업데이트합니다. 서버는 이미 열려 있는 편집기에서 보낸 요청을 포함하여 새 AI 요청마다 현재 권한을 확인합니다. 권한이 없는 사용자도 편집기에서 AI 어시스턴트를 볼 수 있지만 메시지를 보낼 수는 없습니다.

### 사용량 및 초기화

관리자 AI features 탭에는 현재 기간의 **Usage**, **Limit**, **Reset** 버튼이 한 행에 표시됩니다. 사용량은 탭을 열 때 읽히며 계속 갱신되지는 않습니다. 채팅이나 오류 제안이 끝난 후 최신 수치를 보려면 탭을 다시 여세요. 초기화는 즉시 적용되며 해당 사용자의 현재 기간 카운터만 지운 다음 표시된 사용량을 다시 불러옵니다. 계정 양식의 나머지 부분을 저장할 필요는 없습니다.

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

채팅과 오류 제안의 사용량은 하나의 Redis 카운터를 공유하며, 요청이 완료된 후 모델 공급자가 보고한 총 토큰 수로 업데이트됩니다. 여기에는 모델 단계 전반의 입력 및 출력 토큰이 포함됩니다. 입력에는 대화 기록, 문서 컨텍스트, 도구 결과가 포함될 수 있으므로 후속 질문이 새 메시지 자체보다 더 많은 토큰을 소비할 수 있습니다. 한도가 **Unlimited**인 경우에도 사용량은 기록됩니다. 총 토큰 수가 보고되지 않은 요청은 카운터에 더해지지 않으며, 모듈은 과거에 기록되지 않은 사용량을 재구성할 수 없습니다.

할당량 검사는 스트리밍 전에 이루어집니다. 하나의 요청 또는 여러 동시 요청이 이후 요청이 차단되기 전에 남은 허용량을 초과할 수 있습니다. 이는 엄격한 공급자 지출 상한이 아니라 사용 허용량입니다. 할당량 조회에 실패하면 요청이 허용되고 실패가 로그에 기록됩니다.

두 기능 모두 `AI_TOKEN_QUOTA`를 사용하며, 오류 제안에는 별도의 요청 횟수 제한이 없습니다. 카운터를 초기화해도 권한, 동의, 구성된 한도 또는 공급자 자체의 청구 기록은 변경되지 않습니다. 카운터는 UTC 기간 키를 사용하며 40일 후 만료됩니다. Redis 데이터를 유지하면 애플리케이션을 재시작해도 현재 사용량이 보존됩니다.

### 선택적 검색 서비스

웹 검색은 Tavily 호환 API를 사용합니다. 검색 API 키가 구성되어 있으면 사용할 수 있습니다. 이 설정은 AI 게이트웨이와 독립적입니다.

| 변수 | 기본값 | 용도 |
| - | - | - |
| `TAVILY_API_KEY` | 설정 안 됨 | 검색 API 키입니다. `WEB_SEARCH_API_KEY`보다 우선합니다. |
| `WEB_SEARCH_API_KEY` | 설정 안 됨 | 검색 API 키의 대체 이름입니다. |
| `WEB_SEARCH_URL` | `https://api.tavily.com/search` | 검색 엔드포인트입니다. 사용자 지정 엔드포인트는 Tavily 요청 및 응답 형식을 지원해야 합니다. |
| `WEB_SEARCH_MAX_RESULTS` | `5` | 검색당 요청할 결과 수입니다. 서비스가 지원하는 양의 정수를 사용하세요. |
| `WEB_SEARCH_DEPTH` | `basic` | 검색 깊이로, 보통 `basic` 또는 `advanced`입니다. |
| `WEB_SEARCH_PROVIDER` | `tavily` | 현재 구현은 Tavily 호환 프로토콜만 지원합니다. 이 값을 변경해도 다른 어댑터가 선택되지 않습니다. |
| `DOCS_MCP_URL` | `https://docs.overleaf.com/~gitbook/mcp` | 문서 검색 엔드포인트입니다. 문서 검색을 비활성화하려면 빈 문자열로 설정하세요. |

예시:

```dotenv theme={null}
TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp
```

문서 검색은 구성된 GitBook MCP 엔드포인트의 `searchDocumentation` 도구를 호출하며 JSON 또는 SSE 응답을 받습니다. 이는 문서 검색용 MCP 클라이언트입니다. Ayakaleaf 외부의 AI 클라이언트가 프로젝트에서 작업할 수 있도록 하려면 [MCP 서버](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md)를 참조하세요.

웹 페이지 읽기는 v6.4.0 이상부터 도입되었습니다. 채팅은 사용자가 제공한 링크나 검색 결과와 같은 URL로 페이지를 읽을 수 있습니다. 페이지는 외부 URL에서 파일을 가져오는 것과 동일한 서비스인 linked URL 프록시를 통해 가져오므로, [External URL](https://ayakaleaf-pro.mintlify.site/ko/on-premises/configuration/overleaf-toolkit/external-url.md)에 설명된 네트워크 제한도 동일하게 적용됩니다. 추가 설정은 필요하지 않습니다.

검색 쿼리는 구성된 검색 서비스로 전송됩니다. 그런 다음 검색 결과가 AI 게이트웨이 요청에 포함될 수 있습니다. 채팅의 **Tools** 메뉴에서 사용자는 자신의 요청에 대해 **Web**과 **Documentation**을 켜거나 끌 수 있습니다. 모델이 도구를 사용하려면 서버에서도 해당 도구가 구성되어 있어야 합니다.

### Q\&A

> [accordion] 편집기에 AI 어시스턴트가 나타나지 않습니다
>
> **답변:** AI 어시스턴트는 `AI_ENABLED=true`이고 `AI_BASE_URL`, `AI_API_KEY`, `AI_MODEL`이 모두 설정된 경우에만 편집기의 왼쪽 레일에 나타납니다. 이 중 하나라도 누락되면 모든 사용자에게 AI 어시스턴트가 숨겨집니다.
>
> `config/variables.env`를 변경한 후에는 `bin/up -d`로 컨테이너를 다시 생성하세요. 브라우저를 새로 고치는 것만으로는 새 변수가 적용되지 않습니다. 관리자 패널의 **Enable AI features** 스위치는 AI 어시스턴트를 표시하거나 숨기지 않으며, 사용자가 메시지를 보낼 수 있는지만 결정합니다.

> [accordion] 메시지를 보냈지만 AI 어시스턴트가 응답하지 않습니다
>
> **답변:** 먼저 사용자가 AI 어시스턴트에 표시되는 AI 동의 카드를 수락했는지 확인하세요. 수락하기 전에는 메시지를 보낼 수 없습니다.
>
> 그런 다음 web 서비스 로그에서 오류를 찾아보세요.
>
> ```sh theme={null}
> bin/logs web
> ```
>
> | 로그 메시지 | 의미 |
> | - | - |
> | `workbench AI chat requested but no AI gateway is configured` | 실행 중인 컨테이너에 `AI_ENABLED`, `AI_BASE_URL`, `AI_API_KEY`, `AI_MODEL` 중 하나가 없습니다. `bin/up -d`로 컨테이너를 다시 생성하세요. |
> | `workbench chat stream error` | 게이트웨이가 오류를 반환했습니다. 사용자에게는 "The AI service returned an error"가 표시됩니다. 기록된 오류에 게이트웨이의 상태 코드와 메시지가 표시됩니다. |
> | `workbench chat failed` | 스트리밍 전 또는 도중에 요청이 실패했습니다. 예를 들어 게이트웨이에 연결할 수 없는 경우입니다. |
>
> 공급자의 대시보드에 사용량이 표시되지 않으면 요청이 공급자에게 도달하지 않은 것입니다. 일반적인 원인은 다음과 같습니다.
>
> * `AI_BASE_URL`이 잘못되었습니다. 예를 들어 `/v1`이 누락되었거나 중복되었거나, `/chat/completions`가 덧붙여진 경우입니다.
> * 서버가 게이트웨이에 연결할 수 없습니다. 외부로 나가는 트래픽이 프록시를 거쳐야 하는 경우 `AI_PROXY_URL`을 설정하세요.
> * `AI_MODEL`이 게이트웨이가 알고 있는 모델 ID가 아닙니다.
>
> 공급자 측에 요청이 표시되는데도 채팅이 계속 실패한다면, 모델이 스트리밍 채팅 완성과 함수 도구를 지원하는지 확인하세요.

> [accordion] 채팅 기록이 보관되나요?
>
> **답변:** 아니요. 채팅은 열려 있는 브라우저 탭에만 유지됩니다. 페이지를 새로 고치거나 닫으면 지워지며, **Start new chat**은 현재 채팅을 대체합니다. 이전 채팅 목록은 없으며, 각 프로젝트에는 한 번에 하나의 채팅만 표시됩니다.


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