Kimi File-based Q&A

상위 문서: ← Kimi Core workflows 출처: Kimi API Platform 공식 문서 — Use Kimi API for File-Based Q&A 한글화 (2026-07-22) 공급사: Moonshot AI (月之暗面)

Kimi 인텔리전트 어시스턴트는 파일을 업로드해 그 파일에 기반한 질문에 답할 수 있습니다. Kimi API도 같은 기능을 제공합니다.

1. 기본 사용법

import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

# PDF, DOC, 이미지 등 지원 (이미지/PDF는 OCR)
file_object = client.files.create(file=Path("moonshot.pdf"), purpose="file-extract")
file_content = client.files.content(file_id=file_object.id).text

# 추출된 콘텐츠(파일 ID 아님)를 system prompt에 포함
messages = [
    {"role": "system", "content": "You are Kimi, an AI assistant provided by Moonshot AI. You excel in Chinese and English conversations. You provide users with safe, helpful, and accurate answers while rejecting any queries related to terrorism, racism, or explicit content. Moonshot AI is a proper noun and should not be translated."},
    {"role": "system", "content": file_content},  # <-- 추출된 파일 콘텐츠
    {"role": "user", "content": "moonshot.pdf의 내용을 간단히 소개해줘"},
]

completion = client.chat.completions.create(model="kimi-k3", messages=messages)
print(completion.choices[0].message)

2. 단계 요약

1. /v1/files 인터페이스 또는 SDK files.create로 파일 업로드
2. /v1/files/{file_id} 또는 files.content로 콘텐츠 추출 (모델이 쉽게 이해하는 포맷)
3. **추출된 콘텐츠(file ID 아님)**를 messages의 system prompt에 배치
4. 파일 콘텐츠에 대한 질문 시작

⚠️ 다시 강조: 프롬프트에는 file_id가 아니라 파일 콘텐츠를 넣으세요.

3. 다중 파일 Q&A

여러 파일에 대해 질문하려면 각 파일을 별도 system 메시지로 두면 됩니다.

from typing import List, Dict, Any
import os
from pathlib import Path
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

def upload_files(files: List[str]) -> List[Dict[str, Any]]:
    """각 파일을 업로드 → 추출 → system 메시지 리스트 반환"""
    messages = []
    for file in files:
        file_object = client.files.create(file=Path(file), purpose="file-extract")
        file_content = client.files.content(file_id=file_object.id).text
        messages.append({"role": "system", "content": file_content})
    return messages

def main():
    file_messages = upload_files(files=["upload_files.py"])
    messages = [
        *file_messages,  # 파일 메시지 먼저
        {"role": "system", "content": "You are Kimi, an AI assistant provided by Moonshot AI..."},
        {"role": "user", "content": "이 파일들의 내용을 요약해줘"},
    ]
    completion = client.chat.completions.create(model="kimi-k3", messages=messages)
    print(completion.choices[0].message.content)

if __name__ == "__main__":
    main()

4. 파일 관리 모범 사례

파일 업로드·추출은 다양한 형식을 모델이 쉽게 이해하는 포맷으로 변환합니다. 추출 후엔 로컬에 저장하고, 다음 파일 기반 Q&A 요청에서 재업로드·재추출할 필요 없음.

사용자당 업로드 파일 수는 최대 1000개로 제한. 주기적으로 정리하세요:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MOONSHOT_API_KEY"],
    base_url="https://api.moonshot.ai/v1",
)

file_list = client.files.list()
for file in file_list.data:
    client.files.delete(file_id=file.id)

이 코드는 files.list로 모든 파일을 조회한 뒤 files.delete로 각각 삭제. 정기적으로 실행해 파일 저장 공간을 확보.

---

변경 이력

날짜	변경
2026-07-22	초판 작성 (공식 File-based Q&A 가이드 한글화)
2026-07-22	제목에 "Kimi" 접두사 추가, 본문 H1 중복 제거