Knowledge Chat API

Knowledge Chat API는 RAG(Retrieval-Augmented Generation) 기반의 대화형 AI 인터페이스를 제공합니다. OpenAI Chat Completions API와 호환되므로 기존 OpenAI 생태계의 SDK, 라이브러리, 도구를 그대로 활용할 수 있습니다.

OpenAI SDK 호환

이 API는 OpenAI Chat Completions API 사양을 따릅니다. OpenAI Python/JS SDK, LangChain, LlamaIndex 등에서 base_url만 변경하여 직접 사용할 수 있습니다.

Base URL

Knowledge Chat API는 Knowledge Builder 서비스의 /v1 경로에서 제공됩니다. Manager API(/api/v1)와 다른 Base URL을 사용합니다.

엔드포인트

Method	Path	Description
POST	/v1/chat/completions	Chat Completion (스트리밍/비스트리밍)
GET	/v1/models	사용 가능한 LLM 모델 목록

---

Custom Headers

Knowledge Chat API는 RAG 검색 범위와 전략을 제어하기 위한 커스텀 헤더를 지원합니다.

Header	Required	Description
X-Knowledge-Id	Yes	RAG 검색 대상 Knowledge ID
X-Document-Ids	No	검색 범위를 제한할 Document ID (쉼표 구분)
X-RAG-Strategy	No	RAG 전략: vector, text, hybrid, agentic

---

POST /v1/chat/completions

Knowledge 기반 RAG Chat Completion을 수행합니다.

Request Body

Field	Type	Default	Description
model	string	-	LLM 모델 이름 (예: gpt-4o-mini)
messages	array	-	대화 메시지 배열
temperature	float	0.7	생성 온도 (0.0~2.0)
top_p	float	1.0	Top-p 샘플링 (0.0~1.0)
max_tokens	integer	null	최대 생성 토큰 수
stream	boolean	false	SSE 스트리밍 활성화
stop	array|string	null	생성 중지 시퀀스

messages 배열의 각 항목:

Field	Type	Description
role	string	역할: system, user, assistant
content	string	메시지 내용

비스트리밍 응답

200 OK

{
  "id": "chatcmpl-1718448000000",
  "object": "chat.completion",
  "created": 1718448000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "D.Hub에서 파이프라인을 생성하려면..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 256,
    "completion_tokens": 128,
    "total_tokens": 384
  }
}

스트리밍 응답

stream: true로 설정하면 Server-Sent Events(SSE) 형식으로 응답합니다.

Content-Type: text/event-stream

data: {"id":"chatcmpl-1718448000000","object":"chat.completion.chunk","created":1718448000,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-1718448000000","object":"chat.completion.chunk","created":1718448000,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"D.Hub"},"finish_reason":null}]}

data: {"id":"chatcmpl-1718448000000","object":"chat.completion.chunk","created":1718448000,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{"content":"에서"},"finish_reason":null}]}

data: {"id":"chatcmpl-1718448000000","object":"chat.completion.chunk","created":1718448000,"model":"gpt-4o-mini","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

---

GET /v1/models

설정된 LLM 프로바이더에서 사용 가능한 모델 목록을 조회합니다.

Response

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1718448000,
      "owned_by": "openai"
    },
    {
      "id": "gpt-4o",
      "object": "model",
      "created": 1718448000,
      "owned_by": "openai"
    }
  ]
}

---

사용 예시

cURL (비스트리밍)

curl -X POST https://api.dhub.io/v1/chat/completions \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "X-Knowledge-Id: knowledge-abc123" \
  -H "X-RAG-Strategy: hybrid" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "당신은 D.Hub 도우미입니다."},
      {"role": "user", "content": "파이프라인을 생성하는 방법을 알려주세요."}
    ],
    "temperature": 0.7,
    "max_tokens": 1024
  }'

cURL (스트리밍)

curl -X POST https://api.dhub.io/v1/chat/completions \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "X-Knowledge-Id: knowledge-abc123" \
  -H "X-Document-Ids: doc-001,doc-002" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "user", "content": "데이터셋 스키마란 무엇인가요?"}
    ],
    "stream": true
  }'

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.dhub.io/v1",
    api_key="<access_token>",
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "system", "content": "당신은 D.Hub 도우미입니다."},
        {"role": "user", "content": "Knowledge Builder의 검색 모드를 설명해주세요."},
    ],
    temperature=0.7,
    max_tokens=1024,
    extra_headers={
        "X-Knowledge-Id": "knowledge-abc123",
        "X-RAG-Strategy": "hybrid",
    },
)

print(response.choices[0].message.content)

Python (스트리밍)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.dhub.io/v1",
    api_key="<access_token>",
)

stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "D.Hub의 주요 기능을 요약해주세요."},
    ],
    stream=True,
    extra_headers={
        "X-Knowledge-Id": "knowledge-abc123",
    },
)

for chunk in stream:
    content = chunk.choices[0].delta.content
    if content:
        print(content, end="", flush=True)

RAG 전략 선택

• vector: 의미 기반 유사도 검색. 자연어 질문에 적합합니다.
• text: BM25 키워드 검색. 정확한 용어나 코드 검색에 적합합니다.
• hybrid: 벡터 + 텍스트 결합. 대부분의 상황에서 권장됩니다.
• agentic: LLM 에이전트가 검색 전략을 자동으로 결정합니다. 복잡한 질의에 유용합니다.