[OpenAI][Responses API] file search에 날짜 범위를 붙일 때 filename 날짜 규칙과 published_at 숫자 attributes를 어떤 기준으로 먼저 갈라 두나

IT 리서치 노트

[OpenAI][Responses API] file search에 날짜 범위를 붙일 때 filename 날짜 규칙과 published_at 숫자 attributes를 어떤 기준으로 먼저 갈라 두나

Responses API file search에 날짜 범위를 붙이기 시작하면 많은 팀이 filename에 들어간 YYYY-MM-DD 규칙만으로 버티려 한다. 하지만 2026년 7월 15일 기준 OpenAI 공식 문서를 다시 보면 file attributes는 숫자 값을 지원하고, vector store search는 gte, lte 같은 범위 비교도 제공한다. 이 글은 날짜를 filename 규칙에 둘지, numeric published_at attributes로 승격할지를 어떤 기준으로 먼저 나눌지 정리한 것이다.

목차

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

1. 개요

결론부터 말하면 날짜를 단순 제외 규칙으로만 쓰면 filename 날짜도 충분하지만, 기간 비교를 자주 하거나 timezone 보정과 재업로드 보정이 필요하면 published_at 숫자 attribute가 먼저다. 날짜 범위는 문자열 prefix보다 숫자 비교에서 훨씬 덜 흔들린다.

즉 file search 결과가 최신성 때문에 흔들릴수록 schema를 한 단계 더 구조화해야 한다. include 결과와 날짜 로그를 함께 남길 계획이라면 published_at 숫자 모델이 더 안전하다.

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

실무에서 먼저 꼬이는 부분은 세 가지다. 첫째, filename에만 날짜를 넣어 지난 7일과 지난 30일 같은 범위를 자르려고 한다. 둘째, timezone이 다른 업로드가 섞였는데 문자열 정렬만 믿는다. 셋째, 업로드 후 날짜를 수정해야 하는데 filename을 다시 바꾸기 어려워 로그 해석이 꼬인다.

OpenAI 문서는 attributes에 숫자를 둘 수 있고 범위 비교 연산자도 제공한다. 따라서 날짜가 단순한 배치 식별자가 아니라 실제 검색 조건이라면, filename 규칙에만 맡기기보다 숫자 attribute로 올려 두는 편이 맞다.

• 증상: 최신 문서만 찾고 싶은데 결과가 들쭉날쭉하다.
• 실패: YYYY-MM-DD가 filename에 있으니 기간 비교도 충분하다고 본다.
• 막힘: timezone 보정과 재업로드 보정이 filename 모델에서 어렵다.
• 누락: include 결과에 기간 경계를 함께 남기지 않는다.

신호	먼저 볼 것	의미
하루 단위 제외 규칙만 필요	filename 날짜	수집 규칙만으로 충분하다
지난 N일 조건이 자주 바뀜	published_at 숫자	범위 비교 연산자가 필요하다
업로드 후 날짜 보정이 잦음	published_at 숫자	후행 수정이 쉽다

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

실무 순서는 다섯 단계가 가장 안정적이다. 먼저 날짜가 검색 조건인지 수집 규칙인지 확인하고 분리한다. 두 번째로 기간 비교가 필요하면 published_at 숫자 attribute를 생성하고 적용한다. 세 번째로 include 결과와 기간 경계를 함께 기록하고 비교한다. 네 번째로 timezone과 재업로드 보정 규칙을 문서에 적고 수정 기준을 남긴다. 마지막으로 filename 날짜는 보조 식별자로만 두고 실제 필터는 published_at으로 유지한다.

1. 날짜가 검색 조건인지 수집 규칙인지 먼저 확인하고 정한다.
2. 기간 비교가 필요하면 published_at 숫자 attribute를 생성한다.
3. vector store 파일 attributes를 업데이트하고 기준값을 적용한다.
4. gte/lte 경계값과 include 결과를 같은 로그에 기록한다.
5. timezone과 재업로드 보정 규칙을 문서에 적고 재현 절차를 유지한다.
6. filename 날짜는 보조 식별자로만 두고 실제 필터 조건과 비교 로그를 분리한다.

date filter memo

filter_type=date_range
published_at_gte=1751328000
published_at_lte=1752537600
timezone=UTC
filename_date_prefix=2026-07-15
include_results=true

이렇게 정리하면 score threshold와 최신성 문제를 분리하기 쉽다. 날짜 범위가 흔들릴수록 ranker를 만지기보다 published_at 모델과 로그 경계부터 고정하는 편이 맞다.

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

첫 자료는 file search 가이드의 metadata filtering 구간이다. 날짜 범위 문제도 결국 어떤 파일을 먼저 제외할지의 문제로 시작한다.

File search 가이드는 결과 제어의 첫 단계로 metadata filtering을 놓는다.

즉 날짜 범위를 붙일 때도 ranker보다 먼저 filter 모델을 고정해야 한다. 이 점은 일반적인 filename vs metadata 분기보다 더 중요하다.

두 번째 자료는 retrieval 가이드의 attributes 설명이다. file attributes 값은 문자열, 숫자, boolean을 지원하고 key 수 제한도 있다.

Retrieval 가이드는 file attributes를 구조화된 필터 입력으로 설명한다.

여기서 날짜 범위를 filename 문자열 정렬로만 해결하려 하면 한계가 빨리 온다. 기간 비교가 필요한 순간 숫자 attribute가 훨씬 단단하다.

세 번째 자료는 vector store search reference다. 비교 연산자로 gt, gte, lt, lte를 숫자 값에 쓸 수 있다.

Vector store search reference는 숫자 attributes에 범위 비교 연산자를 제공한다.

따라서 날짜 범위를 주간, 월간, 배포 전후처럼 자주 자를 계획이라면 문자열 prefix보다 numeric published_at이 먼저다.

네 번째 자료는 vector store file attributes update reference다. 업로드 뒤에도 attributes를 갱신할 수 있다는 점이 중요하다.

Vector store file attributes는 업로드 후에도 수정 가능하므로 날짜 모델을 후행 보정할 수 있다.

즉 처음에는 filename 날짜 규칙으로 시작했더라도, 운영 중 기간 필터 요구가 커지면 published_at 숫자 attribute로 승격하는 경로를 열어 둘 수 있다.

실무에서는 날짜를 어디에 둘지 먼저 정하는 표가 있어야 한다. filename 날짜와 numeric published_at을 한데 섞어 두면 로그 해석이 더 어려워진다.

filename 날짜 규칙과 numeric published_at attributes를 가르는 분기표다.

이미 filename filter와 metadata key 분기 글을 읽었다면, 이번 표는 그중 날짜 축만 따로 깊게 내려간 것이다.

마지막 자료는 안전한 범위 필터 예시다. 날짜 범위를 운영 로그와 같이 남겨야 include 결과를 다시 읽을 수 있다.

numeric published_at에 범위 비교를 붙이고 include 결과를 남기는 예시다.

이렇게 두면 include 결과 확인 글과 비교 로그 글에 자연스럽게 이어 붙일 수 있다.

5. 주의사항과 리스크

가장 큰 리스크는 날짜를 filename에만 넣고 검색 조건까지 맡기는 것이다. 기간 범위, timezone 보정, 재업로드 보정이 겹치면 문자열 규칙은 설명력이 빨리 떨어진다.

반대로 모든 날짜를 즉시 metadata로 올리는 것도 과할 수 있다. 하루 단위 임시 제외 규칙 정도라면 filename 날짜가 더 단순하다. 핵심은 검색 조건과 수집 규칙을 섞지 않는 것이다.

• 주의: 날짜 범위를 ranker 문제로 오인하면 튜닝 방향이 틀어진다.
• 주의: timezone과 재업로드 보정은 filename 모델에서 점점 비싸진다.
• 주의: include 결과와 날짜 경계를 함께 남기지 않으면 재현이 어렵다.

6. 결론

file search에서 날짜를 검색 조건으로 쓸 계획이라면 filename 날짜는 보조 규칙에 두고, 실제 범위 비교는 numeric published_at attributes로 가져가는 편이 맞다. 이렇게 해야 최신성 필터와 ranking 문제를 분리할 수 있고, timezone과 재업로드 보정도 더 짧게 관리된다. 운영에서는 published_at을 생성하고, filters를 적용하고, include 결과를 확인하고, 경계값을 기록하고, 필요할 때 attributes를 수정하는 흐름까지 한 번에 갖추는 편이 안전하다.

관련 흐름으로는 filename filter와 metadata key 분기 글, include 결과와 ranking 조정 글, 비교 로그 글을 같이 보면 schema, 기간 필터, 검증 로그가 한 줄로 이어진다. 여기에 category와 confidentiality naming 규칙 글을 붙이면 날짜 축과 분류 축을 어떤 key 체계로 나눌지까지 바로 이어서 정리할 수 있다.

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/vector_stores/subresources/files/methods/update/
5. https://developers.openai.com/api/reference/resources/responses/methods/create/