매뉴얼웍스는 OpenAI, Gemini 등이 제공하는 API를 이용해 다양한 AI 어시스턴트(챗봇, AI 글쓰기, 맞춤법 검사와 교정, 아이콘 추천) 기능을 제공합니다. API 기반 AI 어시스턴트를 사용하려면 먼저 AI 제공자를 만들고 AI 모델을 지정해야 합니다.

<AI | AI 제공자> 메뉴는 “관리” 권한이 있는 사용자만 사용할 수 있습니다.

AI 제공자 및 주요 모델

매뉴얼웍스는 Claude, OpenAI, OpenAI 호환, Gemini, Grok, Ollama, OpenRouter, Voyage AI의 8가지 AI 제공자를 지원합니다. 각 제공자에서 지원하는 주요 AI 모델은 다음 표와 같습니다.

AI 제공자	AI 모델	비고
Claude	claude-sonnet-4-0	생성형 AI 모델
	claude-opus-4-0	생성형 AI 모델
	claude-3-5-haiku-latest	생성형 AI 모델
Gemini	gemini-2.5-pro	생성형 AI 모델
	gemini-2.5-flash	생성형 AI 모델
	gemini-2.5-flash-lite	생성형 AI 모델
	gemini-embedding-001	임베딩 AI 모델
Grok	grok-4	생성형 AI 모델
	grok-3	생성형 AI 모델
	grok-3-mini	생성형 AI 모델
Ollama	자세한 내용은 다음을 참고합니다.
OpenAI	gpt-5	생성형 AI 모델
	gpt-5-mini	생성형 AI 모델
	gpt-5-nano	생성형 AI 모델
	gpt-4.1	생성형 AI 모델
	gpt-4.1-mini	생성형 AI 모델
	gpt-4.1-nano	생성형 AI 모델
	gpt-4o	생성형 AI 모델
	text-embedding-3-large	임베딩 AI 모델
	text-embedding-3-small	임베딩 AI 모델
OpenAI 호환	기본으로 제공하는 모델이 없습니다. 서버에 설정한 모델을 사용자 정의 AI 모델로 추가합니다.
OpenRouter	기본으로 제공하는 모델이 없습니다. 사용할 모델을 사용자 정의 AI 모델로 추가합니다.
Voyage AI	voyage-3.5	임베딩 AI 모델
Voyage AI	voyage-3.5-lite	임베딩 AI 모델

매뉴얼웍스는 AI 어시스턴트 기능에 적합한 일부 AI 제공자와 AI 모델을 키워드로 바로 지원합니다. 필요하면 임의의 모델을 등록하여 사용할 수도 있습니다.

AI 제공자 만들기

다음 순서로 AI 제공자를 만듭니다.

<AI | AI 제공자> 메뉴로 이동합니다.
<AI 제공자 만들기> 링크를 클릭합니다.
‘유형’에서 사용할 AI 제공자를 선택하고 기본 정보를 입력합니다.
- 같은 유형의 AI 제공자를 여러 개 만들 수 있습니다.
- 이름은 다른 AI 제공자와 겹치지 않게 정합니다. 앞뒤 공백과 대소문자는 무시하고 비교합니다. AI 모델을 고르는 목록에서 AI 제공자 이름으로 모델을 구분하기 때문입니다.
“API 키”를 입력하고 합니다.

Ollama를 유형으로 선택했을 때는 API 키가 아닌 운영 중인 Ollama의 URL을 입력합니다. Ollama는 API 키 없이 호출합니다.

OpenAI 호환 제공자

매뉴얼웍스 6.0.27 버전부터 OpenAI 호환 제공자를 지원합니다. LiteLLM, vLLM, LM Studio처럼 OpenAI API와 같은 형식으로 요청을 받는 서버를 쓸 때는 “OpenAI 호환”을 유형으로 선택합니다. 사내에 둔 프록시를 거쳐 여러 AI 제공자를 쓰는 경우에도 이 유형을 사용합니다.

URL: 서버의 기본 주소를 입력합니다. 예: http://litellm.example.com:4000/v1
- 채팅은 {URL}/chat/completions, 임베딩은 {URL}/embeddings로 호출합니다.
API 키: 서버가 API 키를 요구할 때만 입력합니다. 비워 두면 Authorization 헤더를 보내지 않습니다.
AI 모델: 기본으로 제공하는 모델이 없습니다. 서버에 설정한 모델 이름을 사용자 정의 AI 모델로 추가합니다.

추가 헤더와 추가 요청 본문 값

매뉴얼웍스 6.0.27 버전부터 모든 AI 제공자의 요청에 헤더와 본문 값을 덧붙일 수 있습니다. 사내 프록시에 사용자 정보를 넘기거나, AI 제공자가 지원하는 옵션을 정할 때 씁니다. AI 제공자 화면의 “추가 헤더”와 “추가 요청 본문 값” 패널에서 <추가> 링크를 클릭해 키와 값을 입력하고, <변경>, <삭제> 링크로 고칩니다. 저장하면 바로 적용하며 채팅과 문서 임베딩 요청에 모두 붙입니다.

추가 헤더: HTTP 요청 헤더로 보냅니다. 값은 항상 문자열입니다.
추가 요청 본문 값: JSON 요청 본문에 덧붙입니다.
- metadata.user_ip처럼 점으로 이은 키는 안쪽 값이 됩니다. 예: {"metadata": {"user_ip": ...}}
- model, messages처럼 매뉴얼웍스가 보내는 값은 덮어쓰지 않습니다.

추가 요청 본문 값은 입력한 값으로 유형을 정합니다.

입력한 값	보내는 값
0, 1.5, -3	숫자
true, false	불리언
"0", "true"	문자열(따옴표 안의 글자)
그 밖의 값	문자열

숫자나 true, false를 문자열로 보내려면 큰따옴표로 감싸 입력합니다. 배열은 지원하지 않습니다.

OpenAI, Gemini 같은 AI 제공자는 알지 못하는 본문 값이 있으면 요청을 거절할 수 있습니다. 이때는 AI 어시스턴트가 답하지 못합니다. AI 제공자의 API 가이드에서 지원하는 값인지 확인한 뒤 입력하고, AI 모델의 <테스트> 링크로 동작을 확인합니다.

변수

추가 헤더와 추가 요청 본문 값에 다음 변수를 쓰면 요청할 때마다 실제 값으로 바꿉니다.

변수	사용자의 요청(챗봇, AI 글쓰기 등)	서버 작업(벡터 저장소 자동 동기화 등)
${userIp}	요청한 사용자의 IP 주소	매뉴얼웍스 서버의 IP 주소
${userId}	로그인한 사용자 아이디. 로그인하지 않은 공개 챗봇은 빈 값	작업을 실행하는 관리자 아이디

리버스 프록시 뒤에서 운영할 때 사용자의 IP 주소는 IP 필터 설정과 같은 규칙으로 구합니다.

LiteLLM 설정 예

LiteLLM은 다음 헤더와 본문 값으로 사용자를 구분해 사용량을 집계합니다. 자세한 내용은 LiteLLM 가이드를 참고합니다.

구분	키	값
추가 헤더	x-litellm-end-user-id	${userId}
추가 요청 본문 값	user	${userId}
추가 요청 본문 값	metadata.user_ip	${userIp}

다른 서버를 쓸 때는 그 서버가 읽는 키 이름으로 입력합니다.

변수를 쓰면 사용자의 IP 주소와 아이디가 AI 서버로 전달됩니다. 개인정보 처리 방침에 맞는지 확인한 뒤 사용합니다.

AI 모델 추가

다음 순서로 AI 모델을 추가합니다.

AI 모델을 지정할 ‘AI 제공자’를 클릭합니다.
“AI 모델” 패널에서 <1AI 모델 추가> 링크를 클릭합니다.
지원하는 모델을 선택하여 추가합니다.
- 각 AI 제공자에는 여러 개의 AI 모델을 지정할 수 있습니다.
- 목록에 없는 모델은 “사용자 정의 AI 모델 추가”를 선택해 추가합니다.
<2테스트> 링크를 클릭하여 선택한 모델의 동작을 테스트할 수 있습니다.
- 임베딩 AI 모델에는 <테스트> 링크가 없습니다.
- <3삭제> 링크를 클릭하여 해당 모델을 삭제할 수 있습니다. AI 어시스턴트나 벡터 저장소에서 사용하는 모델은 삭제할 수 없습니다.

사용자 정의 AI 모델 추가

지원 목록에 없는 모델은 AI 제공자가 쓰는 모델 이름을 직접 입력해 추가합니다. OpenAI 호환과 OpenRouter는 기본으로 제공하는 모델이 없으므로 이 방법으로 추가합니다.

AI 제공자 화면의 “AI 모델” 패널에서 <AI 모델 추가> 링크를 클릭합니다.
목록 맨 아래의 “사용자 정의 AI 모델 추가”를 선택합니다.
“이름”에 AI 제공자가 쓰는 모델 이름을 입력합니다.
임베딩 모델이면 “임베딩 모델” 토글을 켭니다.
- 토글을 켜지 않으면 생성형 AI 모델로 추가합니다.
버튼을 클릭합니다.

모델 이름은 비워 둘 수 없고 200자를 넘을 수 없습니다. 슬래시(/), 역슬래시(\), “..”, 제어 문자는 모델 이름에 쓸 수 없습니다. 같은 AI 제공자에 같은 이름의 모델이 이미 있으면 추가하지 않습니다.

문서 임베딩은 Gemini, OpenAI, OpenAI 호환, Ollama, Voyage AI 제공자에서만 동작합니다. Claude, Grok, OpenRouter 제공자에 임베딩 모델을 추가해도 문서를 임베딩할 수 없습니다.

API 키

API 키 발급받기

AI 제공자마다 API 키를 발급받는 방법이 다릅니다. AI 제공자의 가이드를 참고합니다.

일부 AI 제공자는 API 키 발급 시 신용카드를 이용한 선결제가 필요할 수 있습니다.

AI 제공자	가이드 주소
Claude	https://www.anthropic.com/api
Gemini	https://aistudio.google.com/app/apikey
Grok	https://x.ai/api
OpenAI	https://platform.openai.com/api-keys
OpenRouter	https://openrouter.ai/keys
Voyage AI	https://voyageai.com

API 키 변경하기

<1변경> 링크를 클릭하여 API 키를 변경합니다.

매뉴얼웍스는 UI에서 AI 제공자의 API 키 전체를 노출하지 않고, 일부만 마스킹하여 보여줍니다.

API 키 암호화

매뉴얼웍스 6.0.26 버전부터 AI 제공자의 API 키를 데이터 디렉터리의 암호화 키 파일(.key.json)로 암호화해 데이터베이스에 저장합니다. 이전 버전에서 평문으로 저장한 키는 이 버전으로 업데이트할 때 암호화합니다. 예전 버전의 백업을 복원하거나, 사용자 정보 암호화에서 평문 모드로 쓰다가 암호화 키로 바꿀 때도 암호화합니다.

암호화 키 파일은 매뉴얼웍스 백업에 들어가지 않습니다. 관리자가 따로 안전하게 보관합니다. 암호화 키 파일 없이 백업을 다른 서버에 복원하면 저장된 API 키를 풀 수 없습니다. 이때 AI 제공자 화면에 API 키를 다시 입력하라는 메시지가 나오므로, <변경> 링크로 API 키를 다시 입력합니다.

AI 제공자 삭제하기

<AI | AI 제공자> 메뉴에서 삭제할 AI 제공자를 클릭한 뒤 <삭제> 링크를 클릭합니다. AI 제공자에 추가한 AI 모델도 함께 삭제합니다.

AI 제공자의 AI 모델을 사용하는 AI 어시스턴트가 있거나, 그 AI 모델로 임베딩한 벡터 저장소가 있으면 AI 제공자를 삭제할 수 없습니다. 먼저 AI 어시스턴트의 AI 모델을 바꾸거나 AI 어시스턴트와 벡터 저장소를 삭제합니다.

AI 제공자의 API 사용과 관련한 주의 사항

사용량에 따른 비용 증가

AI 제공자마다 API 사용 비용이 다르게 발생하며, 같은 AI 제공자라도 선택한 모델과 사용 방식에 따라 요금이 달라집니다. 자세한 내용은 각 AI 제공자의 요금 가이드를 참고합니다.

대부분의 AI 제공자는 월 최대 비용 제한 기능을 제공합니다. 이를 설정하는 것을 권장합니다.

AI 모델마다 요금뿐만 응답 속도와 품질도 차이가 납니다.

AI 제공자	비용 가이드 주소
Claude	https://www.anthropic.com/pricing#api
Gemini	https://ai.google.dev/gemini-api/docs/pricing
Grok	https://docs.x.ai/docs/models
OpenAI	https://openai.com/api/pricing/
OpenRouter	https://openrouter.ai/pricing
Voyage AI	https://docs.voyageai.com/docs/pricing

AI 제공자

비용 가이드 주소

Claude

https://www.anthropic.com/pricing#api

Gemini

https://ai.google.dev/gemini-api/docs/pricing

Grok

https://docs.x.ai/docs/models

OpenAI

https://openai.com/api/pricing/

OpenRouter

https://openrouter.ai/pricing

Voyage AI

https://docs.voyageai.com/docs/pricing

데이터 전송에 따른 보안 문제

API를 호출할 때 여러 데이터를 AI 제공자에게 전송합니다. AI 제공자마다 해당 데이터를 처리하는 정책을 공개하고 있으므로, 정확한 내용은 각 제공자의 가이드를 참고합니다.

AI 제공자	데이터 처리 가이드 주소
Claude	https://support.anthropic.com/en/collections/4078534-privacy-legal
Gemini	https://ai.google.dev/gemini-api/terms
Grok	https://docs.x.ai/docs/resources/faq-api/security
OpenAI	https://platform.openai.com/docs/guides/your-data
OpenRouter	https://openrouter.ai/docs/guides/privacy/data-collection
Voyage AI	https://www.voyageai.com/privacy

매뉴얼웍스가 제공하는 AI 어시스턴트별로 AI 제공자에게 전달하는 데이터는 다음과 같습니다.

AI 어시스턴트	전송하는 데이터
문서 임베딩	매뉴얼웍스로 작성한 문서의 전체 내용
챗봇	사용자 입력 사용자 입력에서 추출한 벡터 데이터의 내용
AI 글쓰기	사용자 입력 스타일 가이드를 설정했을 때는 스타일 가이드 장 내용
AI 맞춤법 검사와 교정	단락 내용
AI 아이콘 추천	사용자 입력

각 AI 어시스턴트에 맞는 답변을 얻기 위해 프롬프트를 구성할 때 응답 언어와 응답 형식에 관한 추가 정보를 함께 전달합니다. 이렇게 추가되는 데이터에는 보안과 관련된 내용이 없습니다. 정확한 프롬프트 내용은 REST API 요청 및 응답을 로그 파일에 기록하면 확인할 수 있습니다.