AISheetSense 설치 및 설정 (appendix)

자연어로 시트를 조회하고 제어하는 AISheetSense 를 사용하기 위한 서버 환경 셋팅과 설정 방법을 설명합니다. 이 기능은 클라이언트 플러그인만으로는 동작하지 않으며, 서버 모듈을 함께 설치해야 합니다.

지원 환경

필수 파일

• 서버 모듈은 WAS 환경에 맞는 빌드를 하나만 배치합니다. 맞지 않는 빌드를 넣으면 오류 메시지 없이 챗 다이얼로그만 표시되지 않습니다.
• ai-gateway.properties 경로는 서버 모듈에 고정되어 있어 변경할 수 없습니다. 하위 폴더나 classes 아래에 두면 읽지 못합니다.
• 설정 파일은 배포 파일에 포함된 ai-gateway.properties.sample 을 복사한 뒤 이름을 변경해 사용합니다.

설치 순서

1. 위 3개 파일을 각 지정 위치에 배치합니다.
2. ai-gateway.properties.sample → ai-gateway.properties 로 복사한 뒤 Provider / 모델 / (클라우드의 경우) API 키를 입력합니다.
3. AI 기능을 사용할 페이지에 클라이언트 플러그인을 추가합니다. 플러그인은 ibsheet.js 다음에 로드합니다.

   <script src="assets/ibsheet/ibsheet.js"></script>
   <script src="assets/ibsheet/plugins/ibsheet-aisheetsense.js"></script>
   

4. 시트 생성 옵션에 AISheetSense 를 설정합니다. 서버 모듈 경로를 직접 지정해야 하는 경우 AIUrl 을 함께 설정합니다.

   options.Cfg = {
       AISheetSense: 1
   };
   

5. WAS 를 재시작합니다. 설정 파일은 서버 시작 시점에 한 번만 읽으므로, 이후 설정을 변경한 경우에도 재시작이 필요합니다.

ai-gateway.properties 설정

ai.api-url 기본값

클라우드 LLM (OpenAI / Claude)

API 키가 필요하며 사용량만큼 과금됩니다.

ai.provider=openai
ai.api-key=발급받은_API_키
ai.model=gpt-4o-mini

API 키는 환경변수 AI_API_KEY 사용을 권장합니다. 환경변수가 설정되어 있으면 설정 파일보다 우선 적용되므로, 설정 파일에 키를 평문으로 남기지 않아도 됩니다.

사내 구축형(로컬) LLM

Ollama, vLLM 등 OpenAI 호환 API 를 제공하는 구동 환경이면 사내 서버의 모델을 연결할 수 있습니다. 구동 환경이 무엇이든 ai.provider 값은 항상 local 이며, API 키는 필요하지 않습니다. 인터넷이 차단된 폐쇄망에서도 사용할 수 있고 LLM API 사용료가 발생하지 않습니다.

# Ollama - 기본 포트(11434) 를 사용하는 경우
# ai.api-url 은 local 기본값과 동일하므로 생략 가능
ai.provider=local
ai.model=llama3
ai.api-url=http://localhost:11434/v1/chat/completions

• vLLM 등 기본 주소가 아닌 환경은 ai.api-url 에 해당 주소를 지정합니다.
• 응답이 처리되지 않으면 해당 모델이 JSON 응답 형식을 지원하지 않는 경우이므로 ai.json-format=false 로 설정합니다.
• 로컬 LLM 은 모델 로딩과 추론에 시간이 걸릴 수 있으므로 ai.read-timeout 을 충분히 크게 잡습니다.

이벤트

AI 요청의 전/후 처리는 AISheetSense 전용 범용 이벤트로 제어합니다. 시트 이벤트(options.Events)가 아니라 IBSheet 객체에 직접 설정하며, 모든 시트에 공통 적용됩니다.

사용자 질의 입력
  └→ OnBeforeAI           요청 직전 (파라미터 수정 / 요청 취소 가능)
       └→ 서버 모듈 → LLM Provider
            ├→ 성공 → OnAI
            │          └→ OnBeforeAIApply   시트 적용 직전 (응답 수정 / 적용 취소 가능)
            │               └→ 시트 반영
            └→ 실패 → OnAIError

트러블슈팅

Read More

• AISheetSense cfg
• AIUrl cfg
• OnBeforeAI static
• OnAI static
• OnBeforeAIApply static
• OnAIError static

Since