-
[OpenAI][Responses API] file search에 attribute filtering을 붙인 뒤 ranking_options를 만지기 전에 어떤 비교 로그를 먼저 남기나기타개발지식/AI 2026. 7. 14. 20:13
IT 리서치 노트
[OpenAI][Responses API] file search에 attribute filtering을 붙인 뒤 ranking_options를 만지기 전에 어떤 비교 로그를 먼저 남기나
OpenAI Responses API에서 file search 결과가 기대와 다를 때 많은 팀이 score_threshold를 올리거나 ranker를 바꾸는 것부터 시작한다. 하지만 2026년 7월 14일 기준 OpenAI 공식 문서를 다시 보면 file search는 metadata filtering과 ranking_options를 다른 층위에서 다루고, vector store search 레퍼런스는 filters와 scores를 함께 기록할 수 있게 설계돼 있다. 이 글은 attribute filtering을 이미 붙인 뒤 ranking_options를 만지기 전에 어떤 비교 로그를 먼저 남겨야 tuning 결과를 해석할 수 있는지 정리한 것이다.
1. 개요
결론부터 말하면 ranking_options 실험 전에 filter payload와 result file ids, score 분포를 먼저 기록해야 한다. 그래야 결과가 나빠진 이유가 ranker 때문인지, 애초에 열린 후보 파일군이 잘못됐기 때문인지 구분할 수 있다.
특히 attribute filtering을 붙였다고 해도 attributes 스키마가 일관되지 않으면 같은 query가 매번 다른 파일군을 연다. 그 상태에서 score_threshold만 조정하면 tuning 전후 차이를 잘못 읽게 된다.
2. 어디서 실제로 막히는가
현장에서 흔한 실수는 세 가지다. 첫째, filters를 새로 붙인 뒤 어떤 파일이 후보군에 남았는지 기록하지 않는다. 둘째, score_threshold를 바꾸면서 이전 결과 file ids와 score 분포를 남기지 않는다. 셋째, attributes 키가 파일마다 비어 있거나 형식이 다르다는 사실을 무시한 채 ranking 실험부터 시작한다.
이렇게 되면 'threshold를 0.2에서 0.4로 올렸더니 결과가 좋아졌다' 같은 말이 쉽게 나온다. 하지만 실제로는 threshold를 올린 덕분이 아니라 우연히 이번 파일 배치에 attributes가 잘 붙어 있었을 수도 있다. 반대로 ranking이 아니라 filters가 너무 좁아져서 좋은 파일이 빠진 상황인데 ranker 문제로 오해할 수도 있다.
OpenAI 문서는 metadata filtering을 검색 범위를 좁히는 단계로 설명하고, retrieval 가이드는 attribute_filter로 운영 필드를 조합하라고 적는다. 레퍼런스는 filters와 ranking_options와 score를 모두 요청 단위에서 다룬다. 이 세 문서를 합치면 tuning 전에 비교 로그를 먼저 설계하는 것이 맞다.
- 증상: threshold를 바꿨는데 결과 품질이 좋아졌는지 나빠졌는지 애매하다.
- 실패: filter payload와 result ids를 남기지 않는다.
- 막힘: attributes 스키마 불일치를 ranking 문제로 착각한다.
- 누락: tuning 전후 score 분포를 같은 형식으로 비교하지 않는다.
관찰값 먼저 볼 것 판단 기준 불필요한 파일이 자꾸 섞인다 filters와 attributes 후보군이 잘못 열려 있는지 먼저 본다 결과 수만 줄었다 score_threshold와 score 분포 ranking이 너무 세게 잘랐는지 본다 같은 query인데 매번 결과가 다르다 attributes 스키마 일관성 filter 입력값 자체를 먼저 점검한다 3. 실무에서 적용하는 순서
가장 짧은 순서는 다섯 단계다. 먼저 query와 filter payload를 저장한다. 두 번째로 결과 file ids와 score를 저장한다. 세 번째로 동일 query에서 filters만 바꾸고 ranking은 고정한 비교를 한 번 남긴다. 네 번째로 filters를 고정한 뒤 ranker와 threshold만 바꾼 비교를 남긴다. 마지막으로 두 실험을 섞지 않은 상태에서 답변 품질을 읽는다.
- query와 filter payload를 먼저 저장한다.
- 결과 file ids와 score 분포를 같이 남긴다.
- filters만 바꾼 비교를 한 번 만든다.
- filters를 고정한 뒤 ranker와 threshold만 바꾼다.
- 두 실험을 섞지 않은 상태에서 답변 품질을 본다.
1. query와 filters를 기록한다. 2. result file ids와 score를 기록한다. 3. filters만 바꾼 비교를 실행한다. 4. ranker와 score_threshold만 바꾼 비교를 다시 실행한다.
4. 공식 문서와 예시 화면으로 확인하기
첫 자료는 file search 가이드의 metadata filtering 구간이다. 여기서 OpenAI는 검색 결과를 파일 attributes 기준으로 먼저 좁히는 경로를 설명한다. 즉 엉뚱한 결과가 나올 때 바로 ranker부터 바꾸지 말고, 애초에 어떤 파일 집합을 열어 두고 있는지 먼저 볼 수 있다.
이 단계는 ranking보다 앞단이다. 잘못된 파일이 검색 후보에 이미 들어온 상태라면 score_threshold를 올려도 계속 같은 종류의 잡음이 남을 수 있다.
두 번째 자료는 retrieval 가이드의 attribute filtering 설명이다. OpenAI는 날짜, 문서 타입, 팀 같은 운영 필드를 attributes에 붙여 compound filter로 검색 범위를 구분하라고 안내한다. 이 말은 attribute 스키마가 빈약하면 ranking 실험도 비교 기준이 섞인다는 뜻이다.
예를 들어 모든 파일에 release, owner, source_type 같은 필드가 일관되게 없으면 같은 query라도 어떤 파일이 들어왔는지 매번 달라진다. 그 상태에서 ranking_options만 바꾸면 tuning 결과를 해석하기 어렵다.
세 번째 자료는 vector store search 레퍼런스다. 여기서는 filters와 ranking_options, score를 같은 요청 안에서 다룬다. 즉 검색 품질을 만질 때는 filter가 어떤 후보군을 열었는지와 ranker가 그 후보군을 어떻게 다시 줄였는지를 함께 기록해야 한다.
score_threshold는 결과를 제외하는 문턱값이고, filters는 후보 파일군을 구분하는 조건이다. 둘은 같은 문제가 아니다. 같은 로그 키로 기록하면 나중에 왜 결과가 줄었는지 원인을 잃어버린다.
실무에서는 tuning 전에 비교 로그 표를 먼저 고정하는 편이 가장 효과적이다. query, filter payload, ranker, threshold, result file ids, score 분포를 같은 표에 남기면 filter 문제와 ranking 문제를 분리할 수 있다.
이미 include된 search results와 ranking 순서 글이 결과 해석 순서를 설명했다면, 이번 표는 그 해석을 반복 가능하게 만드는 로그 설계 단계다.
마지막 자료는 안전한 비교 로그 예시다. 핵심은 결과 텍스트 전체를 남기는 것이 아니라 query, filter, ranker, threshold, file ids, score 범위를 남기는 것이다. 이 정도만 있어도 결과가 왜 바뀌었는지 대부분 재현할 수 있다.
이 구조를 잡아 두면 freshness와 generated file 재사용 글이나 file search와 code interpreter 저장 경계 글과도 바로 연결된다.
5. 주의사항과 리스크
result text 전체를 과하게 로그로 남기면 비용과 개인정보 이슈가 동시에 커질 수 있다. 비교 로그는 query, filter, result ids, score 범위처럼 구조화된 지표 위주로 남기는 편이 안전하다.
또 ranker와 filters를 같은 배포에서 동시에 바꾸면 원인 분리가 거의 불가능하다. 응답 품질이 좋아져도 나빠져도 어느 축이 영향을 준 것인지 추적할 수 없기 때문이다.
- 주의: attributes 키가 파일마다 빠져 있으면 ranking 실험은 의미가 약해진다.
- 주의: query rewrite나 max_num_results 변경까지 한 번에 섞지 않는 편이 좋다.
- 주의: tuning 로그는 답변 본문보다 검색 구조를 설명하는 값 위주로 남긴다.
6. 결론
OpenAI file search tuning에서 ranking_options는 마지막 손잡이에 가깝다. 먼저 filter payload, result ids, score 분포를 같은 형식으로 남겨서 후보군 문제와 재정렬 문제를 갈라야 score_threshold 조정이 실제로 도움이 됐는지 판단할 수 있다.
후속으로 더 좁혀 보고 싶다면 include된 search results와 ranking 순서 글, freshness와 generated file 재사용 글을 같이 보면 검색 품질과 저장 전략을 한 흐름으로 묶을 수 있다.
이번 흐름을 한 단계 더 넓게 정리하려면 file search attributes를 설계할 때 filename 필터와 metadata key를 먼저 나누는 글도 이어서 보는 편이 좋다. 비교 로그를 남기는 기준이 결국 어떤 schema를 retrieval용 차원으로 올릴지와 바로 연결되기 때문이다.
7. 참고 링크
'기타개발지식 > AI' 카테고리의 다른 글
