-
[OpenAI][Responses API] web search에서 raw results와 action.sources와 annotations를 언제 각각 저장하나기타개발지식/풀스택개발 2026. 7. 21. 20:14
IT 리서치 노트
[OpenAI][Responses API] web search에서 raw results와 action.sources와 annotations를 언제 각각 저장하나
OpenAI Responses API의 web search를 붙이면 logs에 남길 수 있는 URL 층이 하나가 아니다. 2026년 7월 21일 기준 OpenAI 공식 문서를 다시 보면 annotations는 user-visible citation 층이고, `web_search_call.action.sources`는 tool trace 층이며, `web_search_call.results`는 retrieval 후보 층이다. 이 글은 raw results와 action.sources와 annotations를 언제 각각 저장해야 운영 diff가 덜 꼬이는지 정리한 것이다.
1. 개요
결론부터 말하면 세 층은 목적이 다르다. annotations는 사용자가 본 최종 인용을 남기는 층이고, action.sources는 도구 실행 흔적을 남기는 층이며, raw results는 검색 후보 풀을 복기하는 층이다. 그래서 저장 키도 하나로 합치지 말고 층별로 분리하는 편이 안전하다.
최소 저장 기본값은 annotations와 request config다. action.sources는 tool trace를 디버깅할 때 추가하고, raw results는 retrieval 후보 풀이 왜 바뀌었는지까지 파고들 때만 켜는 편이 비용과 복잡도를 덜 키운다.
2. 어디서 실제로 막히는가
실무에서 흔한 실수는 세 가지다. 첫째, annotations와 action.sources를 모두 같은 sources 키로 저장한다. 둘째, raw results를 항상 켜 두어도 큰 차이가 없을 것이라고 본다. 셋째, request config를 같이 저장하지 않아 user_location이나 search_context_size가 달랐는지 나중에 모른다.
이렇게 되면 citations는 같은데 tool trace만 달라진 경우와, retrieval 후보 풀 자체가 달라진 경우를 분리할 수 없다. 특히 web search 운영에서는 answer diff와 retrieval diff가 다를 수 있는데, 세 층을 하나로 합치면 무엇이 실제로 바뀌었는지 경계가 무너진다.
- 증상: logs에는 sources만 남아 있는데 무엇이 citation이고 무엇이 tool trace인지 모른다.
- 실패: annotations와 action.sources를 같은 의미라고 가정한다.
- 막힘: raw results가 필요한 상황과 과한 상황을 구분하지 않는다.
- 누락: request config를 저장하지 않아 diff 기준점이 사라진다.
질문 먼저 볼 층 이유 사용자가 본 근거가 달라졌나 annotations 최종 답변 citations는 여기 남는다 도구 실행 흔적이 달라졌나 action.sources tool trace 층이기 때문이다 retrieval 후보 풀이 달라졌나 raw results 후보 집합 자체를 봐야 한다 3. 실무에서 적용하는 순서
가장 실용적인 운영 순서는 네 단계다. 먼저 request config를 남긴다. 두 번째로 annotations를 기본 저장값으로 둔다. 세 번째로 action.sources는 tool trace 디버깅이 필요한 서비스에만 켠다. 마지막으로 raw results는 retrieval drift를 직접 복기해야 하는 문제에서만 조건부로 남긴다.
- query, user_location, search_context_size, include를 먼저 저장한다.
- user-visible citation 복기를 위해 annotations를 기본 저장값으로 둔다.
- tool trace가 필요한 경우에만 action.sources를 추가한다.
- retrieval 후보 분석이 필요할 때만 raw results를 별도 저장한다.
이 기준이 중요한 이유는 저장 범위가 넓을수록 diff 로그도 무거워지기 때문이다. 일반적인 customer-facing answer 검증은 annotations만으로 충분하고, production incident나 grounding drift 분석에서만 action.sources와 raw results가 필요하다.
if (goal === "citation_audit") save(annotations) if (goal === "tool_trace_debug") save(action_sources) if (goal === "retrieval_drift") save(raw_results) always_save(request_config)이미 user_location diff 글과 search_context_size diff 글을 읽었다면, 이번 글은 그 아래에서 '무엇을 저장해야 비교가 가능한가'를 더 넓게 정리한 기준표라고 보면 된다.
4. 공식 문서와 예시 화면으로 확인하기
첫 화면은 OpenAI가 annotations를 어디에 두는지 보여 준다. web search guide는 assistant message의 output_text 안에 inline citations가 들어가고, cited URL은 annotations로 남는다고 설명한다.
즉 annotations는 사용자가 실제로 본 답변 근거다. 저장 설계에서 가장 먼저 분리해야 하는 층은 '유저가 본 인용'과 '도구가 훑은 후보'를 같은 sources 배열로 섞지 않는 일이다.
두 번째 자료는 raw results를 어디서 받을 수 있는지 보여 준다. items reference는 include 값으로 web_search_call.results를 지원한다고 적고 있다.
raw results는 retrieval 후보 풀을 복기하는 층이다. answer citations가 왜 그렇게 선택됐는지 파고들 때는 annotations보다 이 층이 먼저 필요할 수 있다.
세 번째 자료는 request config 층의 대표 값인 search_context_size를 보여 준다. web search guide는 tool 설정에서 search_context_size를 조정할 수 있다는 예시를 바로 제시한다.
따라서 persistence 분리는 URL 목록만의 문제가 아니다. request config가 달랐는지까지 같이 남겨야 annotations, action.sources, raw results 중 무엇이 왜 달라졌는지 해석할 수 있다.
실무에서는 세 층의 저장 목적을 한 표로 못 나누면 곧바로 로그가 섞인다. annotations, action.sources, raw results는 질문이 다르기 때문에 키 이름도 분리하는 편이 안전하다.
이미 annotations만 저장하면 부족한 경우를 정리한 글이 기본 분기를 열었다면, 이번 표는 세 층을 언제 켜고 무엇을 비교하는지까지 더 넓게 정리한 허브판이다.
마지막 자료는 실제 저장 계약 예시다. sources라는 한 키에 전부 밀어 넣지 말고 층별로 나누면 다음 diff가 쉬워진다.
이 구조가 있으면 include된 results와 action.sources가 어긋나 보일 때의 로그, search_context_size diff 글을 같은 persistence 체계 안에서 연결하기 쉬워진다.
5. 주의사항과 리스크
첫 번째 리스크는 sources라는 단일 키로 모든 URL을 섞는 것이다. 두 번째는 raw results를 항상 켜 두어 개인정보나 저장 비용을 불필요하게 키우는 것이다. 세 번째는 request config 없이 URL 목록만 저장해 호출 조건이 달랐는지 복기하지 못하는 것이다.
운영 문서에는 최소한 user-visible citation, tool trace, retrieval 후보가 서로 다른 층이라는 전제를 남겨 두는 편이 좋다. 그래야 results와 action.sources 비교 글로 되돌아갈 때도 질문이 엇갈리지 않는다.
6. 결론
web search에서 raw results와 action.sources와 annotations를 언제 각각 저장하느냐는 단순 저장량 문제가 아니다. 무엇이 user-visible 근거인지, 무엇이 tool trace인지, 무엇이 retrieval 후보인지 분리해야 다음 incident에서 answer diff와 retrieval diff를 제대로 나눌 수 있다.
같은 가지의 좁은 후속으로는 results와 action.sources 로그 비교 글, annotations 외 저장 범위 글, search_context_size persistence diff 글을 이어서 보면 좋다.
오늘 기준 더 좁은 운영 후속으로는 action.sources는 같은데 raw results만 달라질 때 query trace와 저장 범위를 다시 나누는 글도 이어서 보면 좋다. 이 글이 저장 층을 먼저 정리했다면, 후속 글은 raw results-only drift가 실제로 생겼을 때 어떤 순서로 조회하고 비교하고 기록할지까지 다룬다.
7. 참고 링크
'기타개발지식 > 풀스택개발' 카테고리의 다른 글
