AI 통합

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

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

​

AI 도우미와 LaTeX 오류 도우미

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

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

​

Toolkit 구성

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

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

AI 제안의 품질은 선택한 모델에 따라 달라집니다. 이미 Codex 또는 ChatGPT 구독이 있다면 CLIProxyAPI의 OpenAI 호환 엔드포인트를 통해 연결할 수 있습니다.

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

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

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 사용 한도를 활성화하려면 다음과 같이 설정합니다.

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

채팅과 오류 제안의 사용량은 하나의 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	문서 검색 엔드포인트입니다. 문서 검색을 비활성화하려면 빈 문자열로 설정하세요.

예시:

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 서버를 참조하세요.

웹 페이지 읽기는 v6.4.0 이상부터 도입되었습니다. 채팅은 사용자가 제공한 링크나 검색 결과와 같은 URL로 페이지를 읽을 수 있습니다. 페이지는 외부 URL에서 파일을 가져오는 것과 동일한 서비스인 linked URL 프록시를 통해 가져오므로, External URL에 설명된 네트워크 제한도 동일하게 적용됩니다. 추가 설정은 필요하지 않습니다.

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

​

Q&A

편집기에 AI 어시스턴트가 나타나지 않습니다

답변: AI 어시스턴트는 AI_ENABLED=true이고 AI_BASE_URL, AI_API_KEY, AI_MODEL이 모두 설정된 경우에만 편집기의 왼쪽 레일에 나타납니다. 이 중 하나라도 누락되면 모든 사용자에게 AI 어시스턴트가 숨겨집니다.

config/variables.env를 변경한 후에는 bin/up -d로 컨테이너를 다시 생성하세요. 브라우저를 새로 고치는 것만으로는 새 변수가 적용되지 않습니다. 관리자 패널의 Enable AI features 스위치는 AI 어시스턴트를 표시하거나 숨기지 않으며, 사용자가 메시지를 보낼 수 있는지만 결정합니다.

메시지를 보냈지만 AI 어시스턴트가 응답하지 않습니다

답변: 먼저 사용자가 AI 어시스턴트에 표시되는 AI 동의 카드를 수락했는지 확인하세요. 수락하기 전에는 메시지를 보낼 수 없습니다.

그런 다음 web 서비스 로그에서 오류를 찾아보세요.

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가 아닙니다.

공급자 측에 요청이 표시되는데도 채팅이 계속 실패한다면, 모델이 스트리밍 채팅 완성과 함수 도구를 지원하는지 확인하세요.

채팅 기록이 보관되나요?

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