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)를 지원해야 합니다. 두 기능 모두 문서 컨텍스트를 이 게이트웨이로 전송하며, 이미지 처리가 가능한 모델을 사용하는 경우 채팅에서 업로드한 이미지도 전송할 수 있습니다.

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_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을 사용합니다.

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

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

사용자 접근 및 동의

인스턴스 가용성과 사용자 권한은 별개입니다. AI_ENABLED와 게이트웨이 구성은 인스턴스 가용성을 제어합니다. 로그인한 사용자는 다음과 같은 기존 계정 검사도 통과해야 합니다.

• aiFeatures.enabled가 false가 아니어야 합니다. 이 기존 데이터베이스 필드는 채팅과 LaTeX 오류 제안을 모두 제어합니다.
• 사용자의 유효한 features.aiUsageQuota가 구성된 무제한 등급(기본값 unlimited)과 일치하거나, 기존 레거시 features.aiErrorAssistant 권한이 활성화되어 있어야 합니다. 유효한 기능에는 적용 가능한 계정 기능 재정의가 포함됩니다.

체크박스를 활성화하는 것만으로는 사용자의 플랜이 변경되지 않습니다. aiUsageQuota 필드는 숫자 토큰 허용량이 아니라 권한 등급입니다. AI_TOKEN_QUOTA는 허용된 각 사용자에게 동일하게 적용되는 별도의 한도이며, 현재 모듈은 계정별 개별 숫자 한도를 제공하지 않습니다.

관리자 사용자 목록에서 사용자를 선택하고 Update account info → AI features를 엽니다. Enable AI features는 계정 변경 사항을 저장할 때 aiFeatures.enabled를 업데이트합니다. 서버는 이미 열려 있는 편집기에서 보낸 요청을 포함하여 새 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 클라이언트이며, 이 모듈은 프로젝트 파일을 MCP 서버로 노출하거나 범용 MCP 서버 레지스트리를 제공하지 않습니다.

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