AI Assistant 모듈 가이드
Jaewoong Heo
2025-12-17
Source:vignettes/ai-assistant-guide-ko.Rmd
ai-assistant-guide-ko.RmdAI Assistant 모듈
jsmodule 패키지를 위한 AI 기반 통계 분석 코드 생성 모듈입니다.
개요
AI Assistant 모듈은 통계 분석을 위한 R 코드를 생성하는 대화형 채팅 인터페이스를 제공합니다. jsmodule의 gadget들과 완벽하게 통합되며 여러 AI 제공자(Anthropic Claude, OpenAI GPT, Google Gemini)를 지원합니다.
빠른 시작
1. API 키 설정
.Renviron 파일에 API 키를 추가하세요:
# .Renviron 파일 열기
usethis::edit_r_environ()
# 다음 중 하나를 추가:
# ANTHROPIC_API_KEY=your_key_here
# OPENAI_API_KEY=your_key_here
# GOOGLE_API_KEY=your_key_here
# 저장 후 R 세션 재시작2. 기본 사용법
옵션 A: jsBasicGadget과 함께 사용
library(jsmodule)
# AI Assistant가 포함된 gadget 실행
jsBasicGadget()
# "AI Assistant" 탭으로 이동옵션 B: 독립 실행형 Shiny 앱
library(shiny)
library(jsmodule)
library(survival)
ui <- fluidPage(
titlePanel("AI Statistical Assistant"),
aiAssistantUI("ai")
)
server <- function(input, output, session) {
data <- reactive(colon)
data.label <- reactive(jstable::mk.lev(colon))
callModule(aiAssistant, "ai",
data = data,
data_label = data.label
)
}
shinyApp(ui, server)주요 기능
코드 생성
- 통계 분석 코드 (회귀분석, 생존분석, 기술통계)
- 시각화 코드 (ggplot2, jskm, forestplot)
- 테이블 생성 (jstable, DT)
- jsmodule 규칙 및 모범 사례 준수
다양한 AI 제공자
- Anthropic Claude (기본값): claude-3-7-sonnet, claude-3-5-sonnet, claude-3-opus
- OpenAI GPT: gpt-4o, gpt-4-turbo, gpt-3.5-turbo
- Google Gemini: gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash
중요 사항
허용된 패키지
생성된 코드는 다음 패키지만 사용할 수 있습니다:
jstable, jskm, jsmodule, survival, ggplot2, ggpubr,
pROC, data.table, DT, gridExtra, GGally, forestploter,
MatchIt, timeROCAPI 키 우선순위
-
callModule()의 명시적api_key인자 - UI 입력 (
show_api_config = TRUE인 경우) - 환경 변수 (
.Renviron파일)
API 설정 모드
show_api_config 파라미터는 API 키 관리 방식을
제어합니다:
show_api_config = TRUE (기본값)
- 사용 사례: 개발, 개인 사용, 또는 사용자가 자신의 API 키를 제공하는 경우
-
동작:
- UI에 Settings 패널 표시
- 사용자가 AI 제공자와 모델 선택 가능
- 사용자가 인터페이스에서 직접 API 키 입력 가능
- UI에 입력된 API 키가
.Renviron파일보다 우선
- 보안 참고: UI에 입력된 API 키는 브라우저 메모리에만 저장되며 디스크에 저장되지 않음
- 권장 사항: 로컬 개발 및 단일 사용자 애플리케이션에 적합
# 개발 모드 - 사용자가 UI에서 설정 가능
aiAssistantUI("ai", show_api_config = TRUE) # 기본값
callModule(aiAssistant, "ai",
data = data,
data_label = data.label,
show_api_config = TRUE
)
show_api_config = FALSE
- 사용 사례: 프로덕션 배포, 공유 애플리케이션, 또는 사전 구성된 환경
-
동작:
- Settings 패널 완전히 숨김
-
.Renviron파일 또는 명시적api_key인자만 사용 - API 설정을 위한 UI 요소 없음
- 보안 참고: 사용자가 API 키를 보거나 수정하는 것을 방지
- 권장 사항: 공유 API 키를 사용하는 프로덕션 배포에 필수
# 프로덕션 모드 - .Renviron에서만 API 키 읽기
aiAssistantUI("ai", show_api_config = FALSE)
callModule(aiAssistant, "ai",
data = data,
data_label = data.label,
show_api_config = FALSE
)고급 사용법
사용자 정의 변수 구조
server <- function(input, output, session) {
data <- reactive(lung)
data.label <- reactive(jstable::mk.lev(lung))
# 변수 역할 정의
var_struct <- reactive({
list(
variable = names(lung),
Base = c("age", "sex", "ph.ecog"),
Event = "status",
Time = "time"
)
})
callModule(aiAssistant, "ai",
data = data,
data_label = data.label,
data_varStruct = var_struct
)
}분석 컨텍스트
AI 응답을 개선하기 위해 배경 정보를 제공하세요:
callModule(aiAssistant, "ai",
data = data,
data_label = data.label,
analysis_context = reactive({
"NCCTG 폐암 임상시험 데이터.
주요 결과: 사망까지의 시간 (status/time).
수행능력 점수(ph.ecog)를 예측 변수로 중점 분석."
})
)프로덕션 배포
프로덕션 환경에서는 API 설정 UI를 숨기세요:
ui <- fluidPage(
aiAssistantUI("ai", show_api_config = FALSE)
)
server <- function(input, output, session) {
callModule(aiAssistant, "ai",
data = data,
data_label = data.label,
show_api_config = FALSE # .Renviron만 사용
)
}문제 해결
API 키를 찾을 수 없음
문제: “API key not configured” 오류
해결책:
-
.Renviron파일에 올바른 변수명이 있는지 확인 -
.Renviron편집 후 R 세션 재시작 - 키가 유효한지 확인 (터미널에서 테스트:
Sys.getenv("ANTHROPIC_API_KEY"))
제한사항
- 외부 데이터 접근 불가: 파일을 읽거나 데이터베이스에 연결할 수 없음
- 제한된 패키지 범위: 허용된 패키지만 사용 가능
- 컨텍스트 윈도우: 매우 긴 대화는 초기화가 필요할 수 있음
- 시각화 미리보기: 일부 복잡한 플롯은 즉시 렌더링되지 않을 수 있음
- 통계 전문성: AI는 코드를 제공하지 통계 컨설팅을 제공하지 않음
보안 고려사항
코드 실행 보안
환경 인식 실행 (개발 vs 프로덕션)
AI Assistant 모듈은 보안과 사용성의 균형을 위해 환경 인식 코드 실행을 구현합니다:
개발 모드 (기본값): - 표준 eval()
함수로 코드 실행 - 디버깅과 개발이 용이 - 모든 콘솔 출력 표시 - 로컬,
신뢰할 수 있는 환경에 적합
프로덕션 모드: -
RAppArmor::eval.secure()로 샌드박스 실행 (Linux 전용) -
향상된 보안 및 리소스 제한: - 1GB RAM 제한 - 1MB 파일 크기 제한 - 10초
타임아웃 - 새 프로세스 생성 금지 - 시스템 명령 실행 방지 - 공개 배포 시
필수
환경 감지: 모듈은 다음을 통해 프로덕션 환경을 자동 감지합니다:
-
DEPLOYMENT_ENV환경 변수 (production또는development) - shinyapps.io 배포 감지
- RStudio Connect 감지
-
.production마커 파일
배포 모드 설정:
로컬 개발용 (기본값):
# 별도 설정 불필요 - 기본값이 개발 모드
# 또는 .Renviron에 명시적으로 설정:
# DEPLOYMENT_ENV=development프로덕션 배포용:
# .Renviron 파일에 추가:
# DEPLOYMENT_ENV=production또는 마커 파일 생성:
Linux 서버 설정 (RAppArmor용):
# AppArmor 설치
sudo apt-get install apparmor apparmor-utils libapparmor-dev
# R 패키지 설치
R -e "install.packages('RAppArmor')"플랫폼 지원:
- ✅ Linux: 완전한 RAppArmor 샌드박싱 사용 가능
- ⚠️ macOS/Windows: 프로덕션 모드에서 경고와 함께 표준 eval로 폴백
- 권장사항: 최대 보안을 위해 Linux 서버에 배포
API 키 보안
⚠️ 중요: API 키 처리 방식
API 키 사용 방법:
- API 키는 환경 변수(
.Renviron) 또는 UI 입력에서 읽음 - UI에 입력된 경우, 키는 현재 R 세션 메모리에만 존재
- API 호출은
httr패키지를 사용하여 AI 제공자 API로 전달
오픈소스입니다:
- 모든 코드는 https://github.com/jinseob2kim/jsmodule 에서 공개되어 감사 가능
- 숨겨진 API 키 저장이나 전송 없음
- 코드를 직접 검토할 수 있습니다
✅ 이 모듈이 API 키로 하지 않는 것:
- 어디에도 저장하지 않음
- 로그에 기록하지 않음
- AI 제공자 외에는 전송하지 않음
✅ AI 제공자로 전송되는 것:
- 사용자의 질문과 프롬프트
- 데이터 구조 정보 (변수명, 타입, 요약 통계)
- 이전 대화 기록
- 생성된 코드 (오류 수정용)
전송되지 않는 것:
- 원시 데이터 값 (질문에 명시적으로 포함하지 않는 한)
- 파일 시스템 정보
배포 유형별 모범 사례
개인/데스크톱 사용 (권장):
# .Renviron에 API 키 저장 (사용자 홈 디렉토리)
# 사용자 계정에만 비공개로 유지됩니다
# ANTHROPIC_API_KEY=your_key_here팀/공유 사용:
- 각 팀원이
.Renviron에 자신의 API 키를 사용해야 함 - 개별 설정을 허용하려면
show_api_config = TRUE설정 - 사용자 간 API 키를 공유하지 마세요
공개 웹 애플리케이션:
- ⚠️ 권장하지 않음:
show_api_config = TRUE로 공개 배포하지 마세요 - 공개 배포가 필요한 경우 다음 대안을 고려하세요:
- 서버 측 API 프록시 구현 (커스텀 백엔드 필요)
- 접근을 제한하는 인증 사용
- 엄격한 사용량 할당 및 모니터링 설정
권장 보안 설정
최대 보안을 위해:
# 1. .Renviron에 API 키 저장 (코드에 절대 포함하지 않음)
usethis::edit_r_environ()
# 추가: ANTHROPIC_API_KEY=your_key
# 2. 프로덕션에서는 show_api_config = FALSE 사용
aiAssistantUI("ai", show_api_config = FALSE)
# 3. .Renviron을 버전 관리에 커밋하지 않음
# .gitignore에 추가:
# .Renviron
# .Renviron.local
# 4. API 키를 정기적으로 교체 (90일마다 권장)
# 5. 제공자의 대시보드를 통해 API 사용량 모니터링지원
이슈나 기능 요청은 다음에서 제출해주세요: https://github.com/jinseob2kim/jsmodule/issues