AI 초보자 QnA
질문
OpenAI API 파일 검색에서 가져올 결과 수를 줄일 수 있나요?
답변
네. Responses API의
tools
안에 둔
file_search
객체에서
max_num_results
를 지정하면 검색 결과의 최대 개수를 정합니다. API 참조의 허용 범위는 1부터 50까지입니다.
이 글은 이미 파일 검색을 연결한 요청에서 가져올 결과 수를 조절하는 방법입니다. 파일 업로드 개수, 답변 글자 수, 출력 토큰 한도와는 구분하세요. 결과를 줄이면 필요한 근거가 빠질 수 있으므로 답변과 원문을 함께 확인합니다.
짧게 답하면
검색 저장소 확인 → 결과 상한 지정 → 실제 반환 결과 점검 → 답변의 빠진 근거 대조 순서로 시작하세요. 같은 자료와 질문을 유지하면서 값만 바꿔 비교합니다.
vector_store_ids
검색할 벡터 저장소의 ID 목록입니다. 파일 ID와 다릅니다.
max_num_results
검색으로 반환할 결과의 최대 개수입니다. 항상 그 수만큼 나온다는 뜻은 아닙니다.
include
검색 결과를 응답에서 볼 수 있도록 요청하는 별도 항목입니다.
처음 쓰는 사람 기준으로 설명하면
자료 여러 개에서 안내 조건을 찾는데 답변에 필요 없는 내용까지 붙는다고 해 보세요. File search 가이드는
max_num_results
로 결과 수를 줄이면 토큰 사용과 지연 시간을 줄이는 데 도움이 될 수 있지만 답변 품질이 낮아질 수도 있다고 설명합니다. 숫자만 낮추기보다 질문에 필요한 본문과 예외가 함께 남는지 봅니다.
검색 결과는 파일 한 개와 일대일로 대응하지 않습니다. Retrieval 가이드는 검색된 자료에 원본 파일과 관련 텍스트 조각이 들어간다고 안내합니다. 따라서 같은 파일의 여러 부분이 결과에 포함될 수 있으며, 상한을 2로 정했다고 파일 두 개를 반드시 모두 읽는 것은 아닙니다.
File inputs 가이드의
input_file
은 파일을 모델 입력으로 전달하는 경로입니다. 이 글은 그 입력에 숫자를 붙이는 방법이 아니라 벡터 저장소를 검색하는 도구 설정을 다룹니다. 직접 검색하는 Retrieval API의 기본 결과 수를 Responses의 file_search 기본값으로 옮겨 쓰지 마세요.
한 줄 정리: 상한은 검색으로 가져올 자료 수를 조절합니다. 원본 파일 전체를 빠짐없이 읽었는지나 답변이 정확한지는 별도로 검토하세요.
바로 따라 해보기
1단계. 같은 자료와 비교할 질문을 준비합니다.
이미 동작하는 file_search 요청과 벡터 저장소 ID를 확인하세요. 공개 가능한 짧은 시험 자료에서 본문과 예외를 함께 묻는 질문을 고릅니다. 모델·저장소·질문은 유지하고 중요한 원문 위치도 적어 둡니다.
2단계. 도구 안에 결과 상한을 넣습니다.
기존
client.responses.create
의 tools에
{"type":"file_search","vector_store_ids":["실제 저장소 ID"],"max_num_results":2}
형태의 객체를 넣으세요. ID 자리에는 자신의 값을 사용합니다. 최상위 요청에 max_num_results를 새로 붙이는 방식이 아닙니다.
3단계. 실제 검색 결과와 답변을 대조합니다.
요청 최상위에
include=["file_search_call.results"]
를 추가하세요. 응답의 output에서
file_search_call
항목을 찾아 상태와
results
를 보고 파일명·텍스트·점수를 확인합니다. 배열이 없으면 개수를 추정하지 않습니다. 같은 조건에서 상한을 바꿔 근거 누락과 사용량을 비교하세요.
주의할 점
기본 응답의 파일 인용 표식과 검색 결과 목록은 다릅니다. File search 가이드는 검색 결과를 기본적으로 반환하지 않으며 include를 추가해야 볼 수 있다고 안내합니다. 결과 목록이 비어 보이면 도구 호출 여부와 결과 포함 설정부터 나눠 확인하세요.
상한 2를 파일 두 개의 전체 내용이나 답변 두 문장으로 해석합니다. 검색 결과의 단위와 실제 반환 항목부터 확인하세요.
값을 낮추면 비용도 같은 비율로 줄고 정답은 유지된다고 생각합니다. 본문·예외 누락과 실제 사용량을 함께 봅니다.
자료 검색이 가능하다는 이유로 고객 파일이나 비공개 결과를 로그에 남깁니다. 시험 자료의 전송 권한과 공유 범위를 먼저 확인하세요.
웹사이트와 앱 중 무엇부터 쓰면 좋을까요?
설정 위치는 공식 웹 문서에서
File search의 결과 수 제한과 Create a model response의 도구 필드를 나란히 읽으세요. 숫자의 위치와 허용 범위를 확인한 뒤 기존 요청 한 곳만 수정합니다.
비교는 API 개발 환경에서
ChatGPT 웹·모바일 앱의 파일 첨부 메뉴에서 바꾸는 설정은 아닙니다. API 응답과 원문을 함께 보고, 검색 결과가 적다는 이유만으로 같은 생성 요청을 무작정 반복하지 마세요.
같이 보면 좋은 질문
확인한 공식 자료
OpenAI 공식 가이드 — File search — 결과 수 제한의 위치, 품질과 사용량의 절충, 검색 결과 포함 설정을 확인했습니다.
OpenAI API 참조 — Create a model response — file_search의 max_num_results 범위와 호출 결과의 results 항목을 확인했습니다.
OpenAI 공식 가이드 — Retrieval — 검색 결과의 파일 정보·텍스트 조각과 별도 직접 검색 경로를 확인했습니다.
OpenAI 공식 가이드 — File inputs — input_file로 직접 전달하는 입력과 File Search를 사용하는 경로의 차이를 확인했습니다.
감자나라 AI 강의보기 5,000 
