사내 문서 검색 만들기 — 임베딩 API 첫 코드와 한국어 토큰 실측

사내 규정·매뉴얼 검색은 문서 조각을 임베딩해 두고, 질문과 가장 가까운 조각만 채팅 모델에 넣어 답하게 하면 돼요. 원포트 AI API 키 하나로 https://oneport.kr/v1 에서 임베딩과 답 생성을 같이 불러요. 쓰던 OpenAI SDK 가 있다면 base_url 만 바꾸면 돼요.

원포트가 시험 문서로 재 보니 한글 문서 100만 자를 text-embedding-3-small 로 색인해도 약 18 크레딧을 한 번 사용했어요. 질문이 쌓이면 크레딧은 대부분 답을 만드는 쪽에서 나가요.

1 크레딧 = 부가세 포함 2원어치예요.

혼자 붙여 볼 거라면 /pricing 에서 원포트 AI API 크레딧을 고르고 사면 바로 돌려 볼 수 있어요. 여러 개발자가 쓰거나 세금계산서·보안 검토가 필요한 회사라면 도입 문의로 알려 주세요.

문서와 질문은 같은 임베딩 모델로 받아야 해요. 모델이 다른 벡터끼리는 비교할 수 없어요.

1. 1문서를 쪽·절 단위 조각으로 나눠요.
2. 2조각마다 임베딩을 받아 벡터를 저장해요. 처음 한 번, 그리고 문서가 바뀔 때만 해요.
3. 3질문이 오면 질문도 임베딩해서, 코사인 유사도가 높은 조각 몇 개를 골라요.
4. 4고른 조각만 질문과 함께 채팅 모델에 넣어 답을 받아요.

openai 파이썬 패키지를 쓰고, 주소만 원포트로 바꿔요. pip install openai 로 설치하고 환경 변수 ONEPORT_API_KEY 에 키를 넣은 뒤 실행해요. 코드에 키 원문을 적지 않아요. 키가 없으면 구매할 때 받을 메일로 「키 받기」 링크가 와요.

import math
import os

from openai import OpenAI

client = OpenAI(base_url="https://oneport.kr/v1", api_key=os.environ["ONEPORT_API_KEY"])

EMBED = "text-embedding-3-small"
CHAT = "claude-haiku-5-5"

# 예시 규정이에요. 숫자는 지어낸 값이니 실제 문서로 바꿔요.
docs = [
    "연차를 쓰려면 3일 전까지 팀장에게 신청해요.",
    "출장비는 다녀온 뒤 7일 안에 영수증을 붙여 정산해요.",
    "재택근무는 팀장 승인을 받아 주 2일까지 할 수 있어요.",
    "비품은 신청서를 내면 다음 주 월요일에 나눠 줘요.",
]

def embed(texts):
    r = client.embeddings.create(model=EMBED, input=texts)
    return [d.embedding for d in r.data]

def cos(a, b):
    dot = sum(x * y for x, y in zip(a, b))
    return dot / (math.sqrt(sum(x * x for x in a)) * math.sqrt(sum(y * y for y in b)))

doc_vecs = embed(docs)  # 색인: 한 번만

question = "출장 다녀오면 정산은 언제까지 해야 해요?"
q_vec = embed([question])[0]  # 질문마다

top = sorted(range(len(docs)), key=lambda i: cos(q_vec, doc_vecs[i]), reverse=True)[:2]
context = "\n".join(docs[i] for i in top)

answer = client.chat.completions.create(
    model=CHAT,
    messages=[
        {"role": "system", "content": "아래 사내 문서만 근거로 답하고, 없으면 모른다고 해요.\n\n" + context},
        {"role": "user", "content": question},
    ],
)
print(answer.choices[0].message.content)

원포트가 시험 문서로 text-embedding-3-small 색인을 돌려 실제 차감 토큰을 쟀어요. 한글이 많은 문서는 대략 1자가 1토큰, 영어 문서는 약 4자가 1토큰이었어요.

다른 임베딩 모델은 토큰 세는 법이 다를 수 있어 이 비율을 옮겨 쓰지 않아요.

예를 들어 claude-haiku-5-5 는 /api 표에서 입력 100만 토큰당 92 크레딧이라, 고른 조각이 4,000토큰이면 입력만 약 0.37 크레딧을 사용해요. 출력 몫은 답 길이만큼 더해져요. 같은 조각이 질문마다 다시 들어가서, 질문이 쌓일수록 색인보다 이쪽이 커져요.

조각은 고른 모델의 입력 상한보다 넉넉히 작게 잘라요. gemini-embedding-001 은 입력 상한이 2,048토큰이라 다른 세 모델보다 조각을 작게 잘라야 해요.

임베딩 모델을 바꿀 땐 색인을 처음부터 다시 해요. 구글 문서는 gemini-embedding-001 에서 2 로 옮길 때 「you must re-embed all of your existing data」라고 적어요.

색인을 돌리는 배치와 서비스가 쓰는 키를 따로 만들고, 키마다 한 달 한도를 걸어 둬요. 색인이 키 한도에 닿아도 서비스 키는 그대로 써요. 다만 지갑 잔액은 두 키가 같이 쓰니 큰 색인 전에 잔액을 봐요. 같은 그룹에 붙인 키라면 그룹 상한도 같이 써요.

원포트는 임베딩·채팅으로 보낸 요청 본문을 남기지 않고 사용량만 기록해요. 각 AI 회사 쪽 처리는 그 회사 정책을 따라요. 만든 벡터와 조각 원문은 직접 둔 저장소에 남으니, 그 저장소의 접근 권한을 정해 두세요.

여러 개발자의 키·한도, 견적·세금계산서, 보안 검토 질문까지 한 번에 정하려면 도입 문의의 「필요한 것」에서 「API」를 골라 남겨 주세요. 늦어도 다음 영업일 안에 연락드려요.