[OpenAI][Responses API] file search 결과가 어긋날 때 include된 search results 확인과 ranking_options 조정을 어느 순서로 나누나

IT 리서치 노트

[OpenAI][Responses API] file search 결과가 어긋날 때 include된 search results 확인과 ranking_options 조정을 어느 순서로 나누나

Responses API에서 file search 결과가 어긋나면 많은 팀이 곧바로 score_threshold나 ranker부터 바꾼다. 하지만 2026년 7월 14일 기준 OpenAI 공식 문서를 다시 보면 file search는 기본적으로 실제 search results 본문을 반환하지 않고, Retrieval 가이드는 attribute filtering과 ranking_options를 서로 다른 층으로 설명한다. 이 글은 결과가 어긋날 때 include된 search results 확인과 ranking_options 조정을 어떤 순서로 나눠야 설명 가능성과 조정 속도가 둘 다 좋아지는지 정리한 것이다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 file search 결과가 어긋날 때는 먼저 include로 실제 search results를 남기고, 그다음 검색 대상 집합이 맞는지 attribute_filter를 보고, 마지막에 ranking_options를 조정한다. include 없이 ranking을 먼저 건드리면 무엇이 좋아졌는지와 무엇이 빠졌는지를 설명할 수 없다.

이미 built-in tools 구조 글이 어떤 도구를 붙일지 다뤘다면, 이번 글은 file search 하나를 붙인 뒤 relevance를 어떻게 디버깅할지의 순서다. 또 vector store freshness 글은 데이터 갱신 축이고, 이번 글은 relevance tuning 축이다.

2. 어디서 실제로 막히는가

현장에서 흔한 막힘은 네 가지다. 첫째, annotations만 보고도 근거를 다 봤다고 착각한다. 둘째, 검색 범위가 너무 넓은데 score_threshold만 올린다. 셋째, 파일 업로드 시 attributes를 안 넣어 filter를 쓸 수 없는데 relevance를 ranking 문제로만 본다. 넷째, stale data와 low relevance를 같은 증상으로 묶는다.

OpenAI file search 가이드는 search results가 기본 응답에 포함되지 않는다고 적고 있고, Retrieval 가이드는 attribute_filter를 semantic search 전에 적용하는 범위 제어로 설명한다. 또 ranking_options는 결과 relevance가 부족할 때 ranker와 threshold를 조정하는 단계라고 적는다. 즉 evidence, scope, ranking은 서로 다른 레이어다.

• 증상: 답변은 나오지만 근거가 엉뚱한 파일에서 온다.
• 실패: include 없이 output_text와 annotations만 저장한다.
• 막힘: 검색 대상 집합이 넓은데 threshold만 높인다.
• 누락: file attributes 설계가 없어 filter를 시도조차 못 한다.

상황	먼저 볼 것	판단 기준
근거가 왜곡돼 보인다	include된 results	실제 chunk와 file_id를 본다
다른 지역/카테고리 문서가 섞인다	attribute_filter	후보 집합 자체를 먼저 줄인다
비슷한 파일끼리 우선순위가 흔들린다	ranking_options	ranker와 score_threshold를 그다음 조정한다

3. 실무에서 적용하는 순서

가장 실용적인 순서는 다섯 단계다. 먼저 include: ["file_search_call.results"]를 켜서 실제 근거를 남긴다. 두 번째로 file ids와 chunk text를 저장한다. 세 번째로 결과가 다른 지역이나 카테고리에서 온다면 attribute_filter를 추가한다. 네 번째로 같은 후보 집합 안에서도 순서가 어긋날 때에만 ranking_options를 조정한다. 마지막으로 freshness 문제인지 relevance 문제인지를 별도 로그로 분리한다.

1. include로 실제 search results를 남긴다.
2. file_id와 chunk 내용을 같은 trace로 저장한다.
3. 필요하면 attribute_filter로 후보 집합을 줄인다.
4. 그다음 ranking_options를 조정한다.
5. freshness와 relevance를 별도 원인 코드로 남긴다.

운영 로그 예시

trace_id=retrieval_2026_07_14_01
result_file_ids=file_a,file_b
attribute_filter={"region":"KR","category":"support"}
ranker=auto
score_threshold=0.18
triage_stage=evidence_first

핵심은 evidence를 먼저 확보하는 것이다. include 결과를 보고도 파일 범위가 잘못됐으면 filter를 손대고, 범위는 맞는데 순서만 애매하면 그때 ranking_options를 본다. 이 순서를 팀 룰로 정해 두면 threshold를 무작정 올리다가 recall까지 잃는 일을 줄일 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 자료는 file search 가이드의 include 구간이다. OpenAI는 annotations는 출력 텍스트 안에 남지만, 실제 search results는 기본 응답에 포함되지 않는다고 적고 있다. 그래서 결과가 어긋난 상황에서 include를 안 켜면 무엇이 검색됐는지조차 모른 채 ranking부터 건드리게 된다.

file search는 기본적으로 search results 본문을 돌려주지 않으므로 include를 먼저 켜야 근거를 남길 수 있다.

이 문장은 triage 순서를 바꾼다. 먼저 결과 근거를 남기고, 그다음 relevance를 조정해야 한다. include 없이 ranking_options를 먼저 바꾸면 무엇이 좋아졌는지 설명할 수 없다.

두 번째 자료는 attribute filtering이다. Retrieval 가이드는 semantic search 전에 파일 속성 기준으로 대상을 좁힐 수 있다고 설명한다. 결과가 어긋난 문제는 때로 ranker보다 먼저 검색 대상 집합을 잘못 넓게 잡은 데서 시작된다.

attribute_filter는 semantic search 전에 검색 대상 파일 자체를 좁히는 단계다.

즉 include로 어떤 파일이 후보에 들어왔는지 확인한 뒤, 범위가 넓다면 attribute_filter를 먼저 본다. ranking은 같은 후보 집합 안의 순서를 바꾸는 도구지, 잘못된 후보 집합 자체를 고치는 도구는 아니다.

세 번째 자료는 ranking_options 설명이다. OpenAI는 results relevance가 충분하지 않을 때 ranker, score_threshold, hybrid search weights를 조정할 수 있다고 적는다. 이건 후보를 본 뒤 relevance를 다듬는 단계다.

ranking_options는 include와 범위 확인 이후 relevance를 다듬는 두 번째 단계다.

여기서 많은 팀이 score_threshold부터 올린다. 하지만 include를 안 켠 상태에서 threshold만 올리면 왜 빠졌는지, 어떤 chunk가 경계에 있었는지 설명할 수 없다. 먼저 증거를 남겨야 한다.

네 번째 자료는 vector_store.file에 attributes를 넣는 예시다. 실제 운영에서 region, category, date 같은 속성을 안 넣으면 attribute_filter로 검색 범위를 자를 수 없다. 결과가 어긋났을 때 범위를 먼저 줄일 수 있는지의 전제 조건이다.

attribute_filter를 쓰려면 파일 업로드 시 attributes 설계부터 있어야 한다.

즉 결과가 자주 엇나르는 팀이라면 ranking_options만이 아니라 ingestion 설계도 봐야 한다. 검색 대상을 좁히는 키가 없으면 결국 score_threshold에 모든 부담이 몰린다.

실무에서는 요청 shape를 한 번 고정해 두는 편이 빠르다. include와 attribute_filter와 ranking_options를 같은 요청에 넣되, 변경 순서는 다르게 가져가면 된다. 먼저 include로 evidence를 열고, 이후 filter와 ranking을 조정한다.

include, attribute_filter, ranking_options를 함께 담더라도 조정 순서는 evidence -> scope -> ranking이 낫다.

이미 file search와 code interpreter 저장 경계 글을 봤다면, 이번 코드는 file search 쪽 근거 저장을 더 세밀하게 다루는 후속편이다. tool을 같이 붙여도 file search 자체의 증거는 따로 남겨야 한다.

마지막 자료는 triage 표다. 결과가 틀렸다고 바로 threshold를 올리지 말고, 먼저 어떤 파일이 들어왔는지와 검색 범위가 맞는지를 본다. 그다음에야 ranker와 threshold를 건드린다.

file search relevance triage는 evidence -> scope -> ranking 순서가 가장 설명 가능성이 높다.

이 표를 기준으로 보면 vector store freshness 글이 stale data 축을 다뤘다면, 이번 글은 stale이 아니라 relevance tuning 축이다. 둘을 섞지 않으면 재실행 범위도 훨씬 짧아진다.

5. 주의사항과 리스크

첫 번째 리스크는 include를 안 켠 채 결과 relevance를 추측으로 조정하는 것이다. 두 번째 리스크는 attributes 설계가 없는데 ranking만 반복 튜닝하는 것이다. 세 번째 리스크는 stale vector store 문제와 relevance 튜닝 문제를 같은 재실행 루프로 돌리는 것이다.

운영 전에 확인할 것은 세 가지다. include 결과가 남는지, 업로드 파일에 filter용 attributes가 있는지, ranking 변경 전후를 비교할 로그가 있는지다. 이 셋이 없으면 ranking 조정이 사실상 블랙박스가 된다.

• include 없는 relevance tuning은 설명 가능성이 낮다.
• attributes 설계가 없으면 scope 문제를 ranking으로 덮게 된다.
• freshness와 relevance는 별도 원인 코드로 남긴다.

6. 결론

Responses API file search 결과가 어긋날 때는 include로 evidence를 먼저 열고, attribute_filter로 검색 범위를 자르고, 마지막에 ranking_options를 조정하는 편이 가장 실용적이다. 이 순서를 지키면 relevance 조정이 설명 가능한 작업이 되고, stale data 문제와도 덜 섞인다.

• 첫 단계는 include된 results 확인이다.
• 두 번째 단계는 filter로 후보 집합을 줄이는 일이다.
• ranking_options는 마지막 조정 레이어로 둔다.

필터를 붙인 뒤에도 결과 차이가 남는다면 ranking 값부터 만지기보다 비교 로그를 어떻게 남길지 먼저 정리해야 한다. 그 순서는 [OpenAI][Responses API] file search에 attribute filtering을 붙인 뒤 ranking_options를 만지기 전에 어떤 비교 로그를 먼저 남기나에서 이어서 다뤘다.

7. 참고 링크

1. https://developers.openai.com/api/docs/guides/tools-file-search
2. https://developers.openai.com/api/docs/guides/retrieval
3. https://developers.openai.com/api/docs/guides/migrate-to-responses