PiGNiTO Platform API

PiGNiTO API란

PiGNiTO Platform API는 기관·기업의 내부 지식을 담은 AI에게 질문하고 답변을 받는 HTTP REST API입니다. 일반 LLM API와 달리, 일상 인사 같은 잡담을 제외한 실제 질의에 대해 기관 지식베이스(문서 + 온톨로지 지식그래프)를 자동으로 검색해 관련 근거를 답변에 반영합니다.

순수 LLM API(예: 범용 챗봇 API)는 모델이 학습한 일반 지식만 답합니다. 우리 기관의 규정·공문·매뉴얼은 모델이 알지 못하므로, 정확한 답을 얻으려면 개발자가 직접 검색 엔진·벡터DB·지식그래프를 구축하고 프롬프트에 근거를 끼워 넣어야 합니다. PiGNiTO API는 그 중간 과정을 서비스로 대신 수행합니다.

이런 곳에 사용합니다

• 기관 홈페이지·민원 시스템의 규정/FAQ 자동 응답
• 내부 업무 포털의 문서 기반 질의응답 봇 연동
• 기존 시스템에 AI 검색 답변 기능을 API로 추가
• 승인·자동화가 포함된 업무 에이전트 실행 (에이전트 실행)

RAG·지식그래프가 만드는 차이

같은 질문을 던져도, 순수 LLM API와 PiGNiTO API의 답은 다릅니다. 차이는 "답변의 근거가 어디서 왔는가"입니다.

내부에서 일어나는 일

클라이언트는 질문만 보냅니다. PiGNiTO가 요청을 받아 아래 단계를 자동 수행하고, 표준 응답 형태로 결과를 돌려줍니다.

[1] 요청 수신          POST /v1/chat/completions  { messages }
[2] 병렬 검색          ① 벡터+BM25 하이브리드 (문서 청크)
                      ② 온톨로지 지식그래프 탐색 (엔티티 관계 1~2-hop)
                      ③ 용어사전(Glossary)   ④ 가상질문(HQG)
[3] 병합·선별          온톨로지 우선 병합 → 유사도 순 → 토큰 예산 내 상위 선택
[4] 프롬프트 주입       <온톨로지 지식> · <용어사전> · <참조 문서> 섹션으로 삽입
[5] LLM 생성          주입된 근거에 기반해 답변 생성
[6] 응답 반환          { choices[].message, pignito.sources }

즉, 개발자 입장에서는 "질문을 보내면 근거 있는 답이 온다"는 한 줄이 전부입니다. 검색 품질을 좌우하는 세부 설정(검색 방식·가중치·범위)은 관리자 콘솔에서 프로젝트 단위로 조정되며, API 호출자는 신경 쓸 필요가 없습니다. (검색 파이프라인 참고)

const client = new OpenAI({
  apiKey: PIGNITO_ACCESS_KEY,
  baseURL: 'https://your-domain.com/v1'
});

const completion = await client.chat.completions.create({
  model: 'pignito/hr-policy-agent',
  messages: [
    { role: 'user', content: '연차는 며칠까지 이월되나요?' }
  ]
});

인증

모든 API 호출은 API 키로 인증합니다. OpenAI와 동일하게 Authorization: Bearer 헤더로 전달하며, 키는 PiGNiTO 콘솔에서 발급됩니다. 하나의 키가 하나의 지식베이스(에이전트)에 연결됩니다.

키 전달 방식

Authorization: Bearer pig-xxxxxxxxxxxx
Content-Type: application/json

OpenAI SDK를 사용하는 경우 api_key 자리에 PiGNiTO 키를 넣으면 됩니다.

키 종류 (프리픽스)

키 종류에 따라 사용자 프로필(역할/부서) 매칭 규칙 적용 여부가 달라집니다. ak_dev_ 이외의 키는 보안을 위해 전달된 사용자 정보를 신뢰하지 않고 게스트 컨텍스트로 동작합니다.

요청 형식

모든 엔드포인트는 /v1 하위 경로에 있습니다(OpenAI API와 동일). 방화벽·프록시 화이트리스트는 {host}/v1/** 전체를 허용하면 됩니다.

응답 공통 규약

응답은 OpenAI 규격을 따릅니다. 채팅은 choices[].message, 목록형(models·files 등)은 { "object": "list", "data": [...] } 형태이며, 실패 시 error 객체와 HTTP 상태 코드를 반환합니다. (오류 코드 참고)

{ "error": { "message": "...", "type": "invalid_request_error", "code": "..." } }

빠른 시작

API 키 하나로 첫 요청을 보내봅니다. curl과 공식 OpenAI SDK 모두 동일하게 동작합니다.

curl https://your-domain.com/v1/chat/completions \
  -H "Authorization: Bearer pig-xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "pignito/hr-policy-agent",
    "messages": [
      { "role": "user", "content": "출장비 정산 기한이 어떻게 되나요?" }
    ]
  }'

from openai import OpenAI

client = OpenAI(
    base_url="https://your-domain.com/v1",
    api_key="pig-xxxxxxxxxxxx",
)

resp = client.chat.completions.create(
    model="pignito/hr-policy-agent",
    messages=[{"role": "user", "content": "출장비 정산 기한이 어떻게 되나요?"}],
)
print(resp.choices[0].message.content)

Chat Completions

OpenAI Chat Completions와 동일한 규격입니다. messages를 보내면 답변 생성 전에 RAG·지식그래프 검색이 자동 수행되어, 근거 기반 답변이 표준 choices[].message 형태로 반환됩니다. stream: true면 표준 SSE 청크로 스트리밍합니다.

{
  "model": "pignito/hr-policy-agent",
  "messages": [
    { "role": "user", "content": "연차는 며칠까지 이월되나요?" }
  ]
}

{
  "id": "chatcmpl-pig-8f3a",
  "object": "chat.completion",
  "model": "pignito/hr-policy-agent",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "미사용 연차는 최대 10일까지 ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 812, "completion_tokens": 96, "total_tokens": 908 },
  "pignito": {
    "sources": [ { "title": "복무 규정 제3장", "score": 0.79 } ]
  }
}

Models

사용 가능한 모델 목록을 조회합니다. OpenAI Models 규격입니다. 목록에는 지식베이스가 연결된 에이전트(pignito/<에이전트>)와 기반 LLM이 함께 반환됩니다.

{
  "object": "list",
  "data": [
    { "id": "pignito/hr-policy-agent", "object": "model", "owned_by": "pignito" },
    { "id": "pignito/finance-agent",   "object": "model", "owned_by": "pignito" },
    { "id": "asnet-local",             "object": "model", "owned_by": "local" }
  ]
}

에이전트 실행

PiGNiTO의 핵심 차별점입니다. 단순 답변을 넘어 스킬(도구)을 실행하는 업무 에이전트를 호출합니다. 계획 수립 → 도구 실행 → 결과 전달까지 처리하며, 위험한 동작은 실행 전 사용자 승인을 요구할 수 있습니다. 요청 형식은 chat/completions와 동일하되(model·messages), 응답이 실행 과정을 담은 SSE 스트림이라는 점이 다릅니다.

event: result             → { result }              중간/최종 응답
event: done               → { success, result }     최종 완료
event: needs-input        → { question }            추가 입력 필요
event: paused             → 승인 대기 (approval-required 별칭)
event: error              → { message }             실행 오류

위젯 연동

웹사이트에 임베드하는 채팅 위젯(초기화·대화 이력·승인 UI·첨부 업로드)은 별도의 위젯 SDK로 제공됩니다.

위젯 설치와 전용 엔드포인트는 별도 문서에서 다룹니다. → SDK 위젯 개발백서

검색 파이프라인 (RAG + 지식그래프)

PiGNiTO는 단일 벡터 검색이 아니라, 4개 채널을 병렬로 검색한 뒤 결합해 근거를 구성합니다. 세부 설정은 프로젝트 단위로 관리자 콘솔에서 조정하며, API 호출자는 값을 직접 넘기지 않습니다. 아래는 서버가 적용하는 기본 구성입니다.

네 채널 결과는 온톨로지 우선 병합(지식그래프가 지목한 문서를 상위 배치)으로 결합된 뒤, 모델 토큰 예산 내에서 상위 항목만 <온톨로지 지식>·<용어사전>·<참조 문서> 섹션으로 프롬프트에 주입됩니다. 검색 방식·가중치·범위는 프로젝트별로 다르게 설정할 수 있습니다.

지원 모델

응답 생성에 사용하는 LLM은 프로젝트 설정에서 지정합니다. PiGNiTO는 Ollama·vLLM 등 OpenAI 호환 로컬 서버에 연결해 온프레미스로 구동하며, 필요 시 외부 상용 API도 함께 지원합니다.

온프레미스 로컬 모델

아래 오픈 모델을 로컬 GPU 서버에서 구동할 수 있습니다. 최소 사양은 4-bit 양자화 기준이며, 컨텍스트 길이·동시 처리량이 커지면 더 필요합니다.

GPU가 없거나 사양이 낮으면 Apple Silicon(Mac M1~) 통합 메모리나 CPU에서도 소형 모델은 구동 가능합니다(속도 저하). 기본 제공 로컬 모델은 ASNET Mac M1 서버에서 운영 중이며, 서빙 모델은 수시로 교체될 수 있습니다.

외부 상용 API

ChatGPT(OpenAI) · Gemini(Google) · Claude(Anthropic) API를 키 등록만으로 연결해 사용할 수 있습니다.

모델 목록·최소 사양은 대표 예시이며, 실제 구동 가능 범위는 설치 환경·양자화 방식·라이선스에 따라 달라집니다.

오류 코드

오류는 OpenAI와 동일하게 HTTP 상태 코드와 error 객체로 반환됩니다.

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}