[OpenAI][Responses API] file search attributes를 설계할 때 filename 필터와 metadata key를 어떤 기준으로 먼저 나누나

IT 리서치 노트

[OpenAI][Responses API] file search attributes를 설계할 때 filename 필터와 metadata key를 어떤 기준으로 먼저 나누나

Responses API file search를 붙인 뒤 결과가 흔들리면 ranking_options부터 만지기 쉽다. 하지만 2026년 7월 15일 기준 OpenAI 공식 문서를 다시 보면 file search는 먼저 filters와 attributes로 검색 대상을 자르고, 그 다음 include 결과와 ranking_options로 relevance를 다듬는 구조다. 이 글은 filename 규칙으로 처리할 분기와 metadata key로 승격할 분기를 어떻게 먼저 나눌지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 장기적으로 반복 결합해야 하는 검색 축은 metadata key로 승격하고, 파일명 규칙만으로 안정적으로 구분되는 축은 filename filter에 남기는 편이 좋다. attributes는 검색 모델의 입력 구조이고, filename은 수집 파이프라인 규칙에 더 가깝다.

따라서 결과가 어긋날 때는 ranking score보다 먼저 schema부터 다시 본다. 어떤 파일이 검색 대상에 남아야 하는지, 어떤 차원은 metadata로 관리해야 하는지, 검증 시 include 결과를 어디까지 같이 저장할지 먼저 고정해야 한다.

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

실무에서 먼저 꼬이는 부분은 세 가지다. 첫째, draft 제외 규칙부터 region, language, publish date까지 전부 metadata key로 밀어 넣어 attributes key가 늘어난다. 둘째, 반대로 category나 confidentiality처럼 검색 중 반복 결합해야 하는 축도 파일명 규칙으로만 처리해 filter 식이 불안정해진다. 셋째, include 결과를 안 남겨 어떤 필터가 실제로 무슨 파일을 자른 것인지 응답만 보고는 확인이 어렵다.

OpenAI retrieval 가이드는 attributes key 수와 길이에 제한을 두고, filename도 별도 filter 대상으로 다룬다. 이는 문서 수집 규칙과 검색 규칙을 같은 서랍에 넣지 말라는 신호에 가깝다. attributes는 검색에서 계속 조합될 비즈니스 차원이고, filename은 ingest 파이프라인에서 이미 드러나는 규칙이면 충분한 경우가 많다.

문제는 많은 팀이 처음에는 단순 규칙으로 시작했다가, 나중에 date range, region, privacy tier, language가 붙을 때도 구조를 안 바꾼다는 점이다. 그러면 filter를 붙일수록 응답 구조가 복잡해지고, file_search_call.results를 봐도 왜 저 파일이 남았는지 금방 설명되지 않는다.

• 증상: filters는 붙었는데 어떤 파일이 남는지 설명이 어렵다.
• 실패: 파일명 규칙과 검색용 metadata를 같은 방식으로 밀어 넣는다.
• 막힘: include 결과를 안 남겨 schema와 ranking을 분리 진단하지 못한다.
• 누락: date range, language, confidentiality 같은 장기 축을 미리 분리하지 않는다.

상황	먼저 볼 것	해석
초안 파일만 빼고 싶다	filename 규칙	metadata key까지 만들 필요가 없을 수 있다
language와 region을 자주 결합한다	metadata key 설계	검색용 차원으로 승격하는 편이 낫다
score threshold를 올려도 결과가 이상하다	include 결과와 schema	ranking이 아니라 대상 집합 문제가 먼저일 수 있다

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

가장 실용적인 순서는 다섯 단계다. 먼저 ingest 단계에서 파일명만으로 안정적으로 구분되는 규칙을 적는다. 두 번째로 검색에서 반복 결합해야 하는 차원을 metadata key 후보로 뽑는다. 세 번째로 attributes key 수를 줄이기 위해 중복 차원을 합친다. 네 번째로 include 결과를 켠 검증 요청으로 실제 남는 파일을 본다. 마지막으로 schema가 안정된 뒤 ranking_options를 조정한다.

1. 파일명만으로 충분한 규칙을 먼저 분리한다.
2. 검색에서 반복 결합할 차원만 metadata key로 승격한다.
3. include 결과를 켜서 실제 남는 파일을 확인한다.
4. schema가 맞는지 본 뒤 ranking_options를 손본다.
5. 응답 로그에는 filters, include 결과, selected files를 함께 남긴다.

schema 검증 메모

filter_strategy=filename|attributes
attributes_used=region,language,category,published_at
include_results=true
selected_filenames=faq_kr.md, release_ko.md
ranking_tuned=false

이 순서가 중요한 이유는 relevance와 scope를 분리하기 위해서다. filename과 metadata를 섞어 두면 scope가 틀렸는데 ranking을 조정하는 잘못된 루프에 빠진다. 반대로 schema가 단단하면 ranking_options는 진짜 quality 조정 수단으로 남는다.

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

첫 자료는 file search 가이드의 metadata filtering 구간이다. OpenAI는 검색 결과를 줄이는 첫 단계를 ranking tuning이 아니라 filters로 설명한다. 즉 결과가 어긋날 때는 먼저 어떤 파일이 검색 대상에 남아야 하는지를 설계해야 한다.

File search 가이드는 ranking 옵션보다 먼저 metadata filtering을 통해 검색 대상을 자르라고 안내한다.

이 문맥을 놓치면 score threshold를 올리고 내리는 일부터 시작하기 쉽다. 하지만 filters가 애매하면 relevance 문제처럼 보이는 데이터 모델 문제가 계속 남는다.

두 번째 자료는 include 옵션 설명이다. file search call은 기본적으로 검색 결과 덩어리를 그대로 돌려주지 않기 때문에, 설계 검증 단계에서는 include로 result payload를 같이 남겨야 attribute schema가 의도대로 먹는지 확인할 수 있다.

include로 file_search_call.results를 함께 남겨야 필터 설계와 ranking 차이를 같은 응답에서 비교하기 쉽다.

즉 attribute 설계는 데이터 저장 시점만의 문제가 아니라, 검색 결과를 어떤 형태로 검증 로그에 남길지의 문제이기도 하다. 이 점이 include 결과와 ranking 조정 글과 직접 이어진다.

세 번째 자료는 retrieval 가이드의 Attributes 구간이다. OpenAI는 각 vector_store.file에 최대 16개 key까지 attributes를 둘 수 있다고 적고, 이 key들을 semantic search 전 필터에 재사용하게 만든다. 즉 key 수와 naming도 운영 제약이다.

Retrieval 가이드는 vector_store.file attributes를 별도 사전처럼 관리하고, key 수와 길이 제한도 함께 둔다.

이 제한이 있기 때문에 filename에 넣어도 되는 분기와 attributes로 승격해야 하는 분기를 나눠야 한다. 모든 차원을 metadata key로 밀어 넣으면 오히려 필터 구조가 무거워진다.

네 번째 자료는 retrieval 가이드의 filename filter 예시다. 문서는 filename도 filter 대상으로 바로 다룰 수 있게 보여 준다. 즉 문서 종류를 파일명 규칙만으로 충분히 나눌 수 있다면 별도 metadata key를 만들 필요가 없을 수 있다.

Retrieval 가이드는 filename 자체를 직접 필터링할 수 있는 예시를 제공한다.

이 차이는 실무에서 중요하다. 문서 생애주기나 카테고리처럼 장기 운영 축은 attributes가 낫고, 배치 산출물이나 draft 제외처럼 파일명 규칙이 강한 축은 filename filter가 더 단순할 수 있다.

실무에서는 key를 어디에 둘지 먼저 정하는 표가 있어야 한다. filename filter와 attributes key를 구분하지 않으면 나중에 filter 식이 길어지고, include 결과를 봐도 무엇이 잘못됐는지 한 번에 안 보인다.

파일명 규칙으로 충분한 축과 metadata key로 승격해야 하는 축을 나눈 비교표다.

이미 attribute filtering 뒤 비교 로그 글을 봤다면, 이번 표는 그 로그를 남기기 전에 schema를 어떻게 고정할지의 선행 단계다.

마지막 자료는 schema 설계 검증용 안전한 예시다. 파일 업로드 시 attributes를 어떻게 두고, 검색 시 include와 filters를 어떻게 같이 남길지 한 묶음으로 보는 편이 좋다.

attribute schema를 바꿀 때는 업로드 구조와 검색 검증 로그를 함께 남겨야 한다.

이렇게 남겨 두면 file search와 code interpreter 결합 글처럼 결과 저장 경로가 여러 개일 때도 어떤 파일이 retrieval 대상이어야 했는지 재구성하기 쉽다.

5. 주의사항과 리스크

모든 축을 metadata key로 만들면 설계가 과해지고 업로드 파이프라인이 복잡해진다. 반대로 검색에서 계속 결합해야 하는 축을 파일명 규칙에만 맡기면 ingest naming이 흔들리는 순간 retrieval 품질도 같이 무너진다.

또 include 결과를 개발 단계에서조차 안 남기면 filter가 잘못됐는지 ranker가 과하게 잘랐는지 설명하기 어려워진다. 실제 운영에서는 schema 변경 전후의 selected files 목록을 짧게라도 남겨 두는 편이 좋다.

• 주의: filename 규칙은 ingest 관점이고 metadata는 retrieval 관점이다.
• 주의: attributes key 수 제한을 무시하면 설계가 빨리 무거워진다.
• 주의: include 결과 없이 ranking부터 조정하면 원인 분리가 어려워진다.

6. 결론

Responses API file search에서 결과를 안정적으로 만들려면 ranking보다 먼저 schema를 고정해야 한다. draft 제외 같은 수집 규칙은 filename 쪽에 두고, region이나 language 같은 검색 차원은 metadata key로 승격한 뒤 include 결과로 실제 남는 파일을 확인하면 filter와 ranking의 역할이 분명해진다.

관련 흐름으로는 include 결과와 ranking 조정 글, attribute filtering 뒤 비교 로그 글, file search와 code interpreter 저장 기준 글을 같이 보면 schema, 로그, 후속 실행 기준이 한 줄로 이어진다. 날짜 범위까지 실제 검색 조건으로 올릴지 고민 중이라면 후속편인 published_at 범위 필터 글을 같이 보면 filename 규칙과 숫자 attributes 역할이 더 선명해진다.

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/reference/resources/vector_stores/methods/search/
4. https://developers.openai.com/api/reference/resources/responses/methods/create/