AI Assistant

외부 AI와 연동하기 위한 패널·도구·실행 API 설정과 사용법을 안내합니다.

RealPivot2는 AI 모델이나 AI 서비스를 제공하지 않습니다.
외부 LLM·에이전트와 연동할 수 있는 패널(UI), 피벗 조작 도구(tool), 실행 API, 그리고 RAG 연동 지점을 제공합니다. 추론, 응답 생성, 지식 코퍼스(Corpus) 관리 등은 연동한 외부 모델이나 서버에서 담당합니다.

Book 개요는 피벗 북(Book)을 참고하세요.

RealPivot2가 제공하는 것

AI 라이선스·API 키·원격 서버·지식베이스 구축·응답 품질은 RealPivot2 범위가 아닙니다. 연동 목적과 사용 환경에 맞춰 직접 구축해야 합니다.

어디에 지정하나요

피벗 북(Book) 설정의 ai 옵션(PivotAIOptions)에서 활성화합니다. 기본값은 enabled: false입니다.

const config = {
  ai: {
    enabled: true,
    models: {
      type: 'remote',
      name: 'my-server',
      modelName: 'gpt-4.1',
      url: 'https://my-ai.example.com/v1',
      headers: {
        Authorization: 'Bearer <YOUR_TOKEN>',
      },
    },
    panel: {
      position: 'right',
      width: 320,
      prompter: {
        suggestions: [
          '판매수량 이상치를 탐지해줘.',
          '판매수량에 데이터바를 적용해.',
        ],
      },
    },
  },
  tables: {
    name: 'sales',
    cube: 'sales',
    // fields ...
  },
};

AI 패널

AI 패널은 외부 LLM과 대화하는 UI 영역입니다. ai.panel.position 옵션으로 위치를 지정할 수 있습니다.

ai: {
  enabled: true,
  panel: {
    position: 'explorer',
    width: 320,
    autoDock: true,
    prompter: {
      greetings: '피벗 구성을 자연어로 요청해 보세요.',
      placeholder: '예: 차종을 행으로 옮겨줘',
      waitingMessage: '분석 중...',
      suggestions: ['국가를 필터에 넣어줘.'],
    },
  },
}

prompter(AIPrompterOptions) 항목은 인사말, 제안어, placeholder 등 패널 UI에 표시될 문구만 설정하며, 실제 답변은 연동된 AI 모델이 생성합니다.

헤더·탭바의 AI 관련 버튼은 ai.enabled가 true일 때 표시됩니다.

외부 모델 연결

ai.models에 개발자가 사용할 모델을 등록합니다. 객체 하나 또는 배열로 지정할 수 있습니다.

원격 서버 (type: 'remote')

자체 백엔드(또는 프록시)를 경유해 LLM을 호출하는 방식입니다.

models: {
  type: 'remote',
  name: 'my-server',
  modelName: 'gpt-4.1',
  url: 'https://my-ai.example.com/v1',
  headers: { Authorization: 'Bearer <YOUR_TOKEN>' },
}

전체 항목은 PivotRemoteAIModelOptions · Config · ai · models를 참고하세요.

브라우저에서 provider API 호출 (type: 'local')

OpenAI·Gemini API를 브라우저에서 직접 호출합니다. provider는 'openai' 또는 'gemini'입니다.

models: {
  type: 'local',
  name: 'gpt',
  provider: 'openai',
  modelName: 'gpt-4.1',
  apiKey: '<YOUR_OPENAI_API_KEY>',
}

전체 항목은 PivotLocalAIModelOptions를 참고하세요.

피벗 도구(tool)

RealPivot2는 LLM이 피벗을 제어할 수 있도록 조작 도구(Tool) 항목들을 제공합니다. 도구 자체는 AI가 아니며, 연동된 AI가 피벗을 변경할 때 호출하는 명령 스키마 목록입니다.

대표 예시는 다음과 같습니다.

옵션 구조가 확실하지 않을 경우, AI가 임의로 추측하기보다는 search_features 도구로 지식베이스를 먼저 검색한 후 반환된 config를 적용하도록 구성하는 것을 권장합니다.

스키마 목록은 getAITools() · exportAITools() · book.aiApi.getToolSchemas()로 확인할 수 있습니다.

import { getAITools, exportAITools } from 'realpivot2';
 
const tools = getAITools();
const schemaJson = exportAITools();

외부 에이전트에서 실행하기

자체 채팅 UI·에이전트를 쓰는 경우에도 book.aiApi(PivotAIApi)로 동일 도구를 실행할 수 있습니다. 내장 AI 패널을 쓰지 않아도 됩니다.

const api = control.book.aiApi;
 
const schemas = api.getToolSchemas();
const state = api.serializeState({ include: ['config'] });
 
const result = await api.execute({
  tool: 'move_field',
  arguments: {
    // 도구별 인자
  },
  reason: '차종을 행 영역으로 이동합니다.',
});

컨텍스트·도구·상태 조회와 실행 진입점이 API에 모여 있습니다. 상세는 API 문서를 참고하세요.

RAG · 리소스

RealPivot2는 지식베이스(코퍼스)를 내장·호스팅하지 않습니다.
대신 AI가 피벗 설정 방법을 스스로 찾도록 RAG 연동을 지원합니다. 컨텍스트 파일·검색 엔드포인트·임베딩 코퍼스는 앱에서 제공합니다.

컨텍스트 파일

ai.resources(PivotAIResourcesOptions)로 모델에 넘길 설명 문서 경로를 지정합니다.

해당 경로의 마크다운(.md) 파일을 웹 애플리케이션에서 접근(서빙)할 수 있도록 설정해야 정상 로드됩니다.

설정 방법 검색 (featureSearch)

search_features 도구가 호출하는 원격 RAG 엔드포인트입니다.
히트맵이나 데이터바 등 복잡한 config 구조를 모를 때, AI가 지식베이스를 검색하여 가져온 설정을 config 도구에 적용할 수 있도록 지원합니다.

요청·응답 계약은 다음과 같습니다.

• 요청: POST body { query }
• 응답: { count, grounding }

ai: {
  enabled: true,
  resources: {
    systemContextPath: 'rag/system_context.md',
    developerContextPath: 'rag/developer_context.md',
    featureSearch: {
      url: '/api/feature-search',
      headers: { Authorization: 'Bearer <YOUR_TOKEN>' },
    },
  },
  // models, panel ...
}

전체 항목은 Config · ai · resources · featureSearch를 참고하세요.

로컬 모델 RAG (useRag)

type: 'local' 모델에서는 질의마다 임베딩 코퍼스를 검색해 프롬프트에 주입할 수 있습니다.
코퍼스 파일도 앱이 서빙하며, RealPivot2는 검색·주입 경로만 제공합니다.

models: {
  type: 'local',
  name: 'gpt',
  provider: 'openai',
  modelName: 'gpt-4.1',
  apiKey: '<YOUR_OPENAI_API_KEY>',
  useRag: true,
  ragTopK: 5,
}

패널 UI 메뉴에서도 로컬 모델의 RAG 활성화 여부를 전환할 수 있습니다.
featureSearch(원격 도구 검색) 방식과 useRag(로컬 프롬프트 주입) 방식은 독립적으로 동작하므로, 상황에 맞춰 개별 또는 조합하여 사용할 수 있습니다.

API로 패널·질의 다루기

const ai = control.book.ai;
const panel = ai.panel;
const prompter = panel.prompter;
 
ai.enabled; // true / false
ai.setActiveModel('my-server');
 
prompter.send('판매수량에 히트맵을 적용해줘.');
prompter.reset();

옵션 변경 규칙은 개발 가이드를 참고하세요.

See Also

• 피벗 북(Book)
• 탐색기(Explorer)
• 필드 구성
• PivotAIOptions
• PivotAiPanelOptions
• PivotLocalAIModelOptions
• PivotRemoteAIModelOptions
• PivotAIApi
• PivotAIResourcesOptions
• Config · ai
• Config · ai · resources
• 데모 · AI