이 문서는 영어 원문을 자동 번역한 것으로, 내용이 원문과 다를 수 있습니다. 영어 원문 보기
File Search는 현재 베타 단계입니다. 기능과 API 사양은 사전 공지 없이 변경될 수 있습니다.
베타 기간 동안에는 민감하거나 기밀에 해당하는 데이터를 업로드하지 마세요.
서비스가 정식 출시될 때, 이용 약관에 동의하지 않은 사용자의 데이터는 삭제될 수 있습니다.
File Search를 사용하면 자연어 쿼리로 문서를 검색할 수 있어요. 파일을 업로드하여 벡터 스토어를 구축한 뒤 관련 정보를 검색하거나, Responses API로 문서에 근거한 AI 답변을 받을 수 있어요.
For AI Coding Assistants
Paste this URL into your agent's context for File Search code generation.
https://console.upstage.ai/docs/capabilities/search/file-search.md
벡터 스토어 는 색인된 문서를 보관하는 컨테이너예요. 벡터 스토어에 파일을 업로드하면, 시스템이 자동으로 콘텐츠를 변환, 분할, 임베딩하여 검색 가능하도록 만들어줘요.
각 벡터 스토어는 격리되어 있으며, 한 벡터 스토어의 파일은 다른 벡터 스토어에서 검색할 수 없어요. 벡터 스토어는 사용자별(API 키로 식별)로 범위가 지정됩니다. 본인이 생성한 벡터 스토어에만 접근할 수 있으며, 다른 사용자는 여러분의 데이터를 보거나 검색할 수 없어요.
벡터 스토어에 파일을 추가하면, 시스템은 비동기 파이프라인을 통해 파일을 처리해요.
변환(Parse) — 파일에서 텍스트 콘텐츠를 추출해요(이미지, PDF, Microsoft Office 문서 등 지원).
청크(Chunk) — 추출된 텍스트를 최적화된 단위로 분할해요.
임베딩(Embed) — 각 청크에 대해 벡터 임베딩을 생성해요.
저장(Store) — 검색을 위해 임베딩을 저장해요.
파일 처리는 비동기로 진행돼요. 파일을 추가하면 상태가 in_progress로 시작되며, 인덱싱이 끝나면 completed로 전환되거나 오류 발생 시 failed로 전환돼요.
검색은 자연어 쿼리를 입력받아 임베딩을 생성하고, 벡터 스토어에서 가장 관련성 높은 문서 청크를 찾아요. 결과에는 일치한 텍스트, 관련도 점수, 출처 파일 정보가 포함돼요.
Responses API는 검색과 LLM을 결합해요. 관련 문서 청크를 검색한 후, 검색된 컨텍스트에 근거한 AI 답변을 생성해요. 이를 검색 증강 생성(Retrieval-Augmented Generation, RAG)이라고도 해요.
이 가이드는 벡터 스토어를 생성하고, 파일을 업로드한 뒤, 첫 번째 검색을 수행하는 과정을 안내해요.
curl Python
curl -X POST https://api.upstage.ai/v2/vector_stores \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
-H "Content-Type: application/json" \
-d '{
"name": "my-knowledge-base"
}'
응답:
{
"id" : "vs_abc123def456" ,
"object" : "vector_store" ,
"created_at" : 1711644800 ,
"name" : "my-knowledge-base" ,
"usage_bytes" : 0 ,
"file_counts" : {
"in_progress" : 0 ,
"completed" : 0 ,
"failed" : 0 ,
"cancelled" : 0 ,
"total" : 0
},
"status" : "completed" ,
"last_active_at" : 1711644800 ,
"expires_after" : null ,
"expires_at" : null ,
"metadata" : {}
} 벡터 스토어에 파일을 추가하려면 업스테이지 Files API 에서 발급한 file_id가 필요해요. 먼저 파일을 업로드한 다음 벡터 스토어에 추가해주세요.
curl Python
curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/files \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
-H "Content-Type: application/json" \
-d '{
"file_id": "file_xyz789"
}'
응답:
{
"id" : "file_xyz789" ,
"object" : "vector_store.file" ,
"created_at" : 1711644900 ,
"vector_store_id" : "vs_abc123def456" ,
"status" : "in_progress" ,
"last_error" : null ,
"usage_bytes" : 0 ,
"chunking_strategy" : { "type" : "auto" },
"attributes" : null
} 파일 인덱싱은 비동기적으로 진행돼요. 파일 상태가 completed가 될 때까지 폴링해주세요.
curl Python
# 상태가 "completed" 또는 "failed"가 될 때까지 폴링
curl -s https://api.upstage.ai/v2/vector_stores/vs_abc123def456/files/file_xyz789 \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
| python3 -c "import sys,json; print(json.load(sys.stdin)['status'])"
curl Python
curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/search \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
-H "Content-Type: application/json" \
-d '{
"query": "What is the main topic of the document?",
"max_num_results": 5
}'
curl Python
curl -X POST https://api.upstage.ai/v2/responses \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
-H "Content-Type: application/json" \
-d '{
"model": "solar-pro4",
"input": "Summarize the key points of my document.",
"tools": [
{
"type": "file_search",
"vector_store_ids": ["vs_abc123def456"]
}
]
}'
확장자 형식 .pdfPDF 문서 .docxMicrosoft Word .pptxMicrosoft PowerPoint .xlsxMicrosoft Excel .hwp, .hwpx한글 워드 프로세서 .md마크다운 .txt일반 텍스트 .jpeg, .jpgJPEG 이미지 .pngPNG 이미지 .bmpBMP 이미지 .tiff, .tifTIFF 이미지 .heicHEIC 이미지
모든 파일 형식은 인덱싱 전에 document parsing을 통해 텍스트 콘텐츠가 추출돼요.
모든 에러는 다음과 같은 일관된 형식을 따라요.
{
"error" : {
"message" : "Description of the error." ,
"type" : "error_type" ,
"code" : null
}
}
HTTP 상태 유형 원인 400 invalid_request_error지원되지 않는 파일 형식, 필수 필드 누락, 또는 서비스 한도 초과(code: "max_limit_exceeded"). 401 — Authorization 헤더의 API 키가 누락되었거나 유효하지 않음.404 — 벡터 스토어 또는 파일을 찾을 수 없음. 422 invalid_request_error잘못된 chunking_strategy(auto만 지원됨), 잘못된 메타데이터 또는 속성(한도 초과).
파일 배치를 사용하면 한 번의 요청으로 여러 파일을 벡터 스토어에 추가할 수 있어요. 한꺼번에 많은 파일을 인덱싱해야 할 때 유용해요.
curl Python
curl -X POST https://api.upstage.ai/v2/vector_stores/vs_abc123def456/file_batches \
-H "Authorization: Bearer $UPSTAGE_API_KEY " \
-H "Content-Type: application/json" \
-d '{
"file_ids": ["file_001", "file_002", "file_003"]
}'
배치 상태를 확인하고 배치에 포함된 파일을 조회할 수 있어요.
# 배치 상태 확인
batch = client.vector_stores.file_batches.retrieve(
vector_store_id = vector_store.id,
batch_id = batch.id,
)
print (batch.file_counts)
# 배치 내 파일 목록 조회
files = client.vector_stores.file_batches.list_files(
vector_store_id = vector_store.id,
batch_id = batch.id,
)
for f in files:
print (f.id, f.status)
진행 중인 배치를 취소하려면:
batch = client.vector_stores.file_batches.cancel(
vector_store_id = vector_store.id,
batch_id = batch.id,
)
배치의 status 필드는 인덱싱이 완료되었는지가 아니라 배치가 취소되었는지를 나타내요. 다음 중 하나의 값을 가질 수 있어요.
in_progress — 생성 시 설정됩니다. 배치 내 모든 파일이 종료 상태에 도달한 이후에도 in_progress로 유지돼요.
cancelled — in_progress 상태의 배치에 대해 POST .../cancel이 호출될 때 설정됩니다. 이미 취소된 배치는 그대로 반환됩니다(no-op).
배치 인덱싱이 완료되었는지 감지하려면 status가 아닌 file_counts를 폴링해주세요. file_counts.in_progress가 0이 되면 배치는 기능적으로 완료된 거예요.
import time
while True :
batch = client.vector_stores.file_batches.retrieve(
vector_store_id = vector_store.id,
batch_id = batch.id,
)
counts = batch.file_counts
if counts.in_progress == 0 :
break
time.sleep( 2 )
# 종료 시점의 카운트 확인
if counts.failed > 0 :
# 일부 파일 인덱싱이 실패함 — filter=failed로 파일 목록을 조회하여 last_error 확인
failed_files = client.vector_stores.file_batches.list_files(
vector_store_id = vector_store.id,
batch_id = batch.id,
filter = "failed" ,
)
파일별 실패는 배치 상태를 변경하지 않아요. 실패는 file_counts.failed에 집계돼요.
리소스 한도 사용자당 벡터 스토어 50 벡터 스토어당 파일 500 배치당 파일 50
이러한 한도는 생성 시점에 적용돼요. 한도를 초과하면 code: "max_limit_exceeded"와 함께 400 에러가 반환돼요.
제약 값 객체당 메타데이터 키 16 메타데이터 키 길이 64자 메타데이터 값 길이 512자 파일당 속성 키 16 속성 키 길이 64자 속성 문자열 값 길이 512자 max_num_results 범위1-20 (기본값: 5) expires_after.days 범위1-365 페이지네이션 limit 범위 1-100 (기본값: 20) 청크 분할 전략 auto만 지원