Cloudflare Markdown for Agents GA: 변환 성공과 토큰 절감률을 검증하는 법

HTML을 Markdown으로 바꾼 뒤 누락과 측정값을 검사하는 흐름을 표현한 생성형 이미지. 실제 Cloudflare 화면은 아니다.

Cloudflare가 2026년 11월 9일 Markdown for Agents의 정식 제공(GA)과 분석·추적 기능을 발표했다. 운영자는 이제 변환 결과, 실패 원인, 일부만 변환된 페이지를 확인하고 Playground에서 HTML과 Markdown을 비교할 수 있다. AI가 읽을 문서를 제공하는 팀에는 얼마나 줄었는지와 무엇이 남았는지를 함께 확인할 수 있다는 점이 중요하다. 공식 발표

먼저 요청 형식과 실제 응답을 나눈다

HTTP의 Accept는 클라이언트가 이해할 수 있는 형식을 서버에 알린다. 서버가 선택한 실제 형식은 응답의 Content-Type으로 확인한다. 따라서 수집기가 Markdown을 요청했다는 이유만으로 반환된 문자열을 곧바로 Markdown으로 처리하면 안 된다. 오류 페이지나 다른 형식이 돌아오는 경로도 별도로 처리해야 한다. MDN Accept

다음은 Cloudflare 공개 문서를 읽는 명령이다. 로그인·API 키·설정 변경 없이 헤더와 본문을 따로 저장한다. 같은 이름의 로컬 파일이 있으면 덮어쓰므로 빈 작업 디렉터리에서 실행한다.

작성 과정의 공개 문서 GET 요청에서는 HTTP 200, content-type: text/markdown; charset=utf-8, vary: accept-encoding, accept를 확인했다. 본문은 제목·설명이 담긴 frontmatter로 시작했다. 이 결과는 해당 문서 한 번의 응답 확인이며 사용자 사이트의 설정이나 변환 품질을 검증한 것은 아니다.

Vary는 캐시가 응답을 구분할 때 참조할 요청 헤더를 알린다. 같은 URL을 HTML로 읽는 브라우저와 Markdown으로 읽는 수집기가 함께 사용한다면, 중간 캐시나 자체 수집 캐시에서도 형식을 섞지 않는지 점검하자. 자체 캐시를 URL만으로 키잉하는 구현은 특히 확인할 만하다. MDN Vary

full을 콘텐츠 검수 완료로 해석하지 않는다

공식 문서의 변환 결과는 다음처럼 구분된다.

full: 변환이 끝났고 콘텐츠 제한 플래그가 모두 거짓이다. HTML의 무손실 보존을 뜻하지 않는다.

partial: 입력 잘림이나 frontmatter·JSON-LD 생략이 발생했다.

completed_unknown: 완료했지만 full과 partial을 판정할 정보가 부족하다.

error: 오류로 종료됐다.

unfinished: 최종 결과에 도달하지 못했고 원인은 확정되지 않았다.

결과 코드의 공식 정의

권장 검수 방법은 문서 종류별로 ‘반드시 남아야 할 내용’을 먼저 정하는 것이다. 예를 들어 API 문서는 매개변수의 필수 여부, 설치 가이드는 명령과 버전 조건, 요금 설명은 적용 범위와 예외를 검사한다. 제목과 첫 문단만 남아도 정상처럼 보일 수 있으므로, 본문 뒤쪽의 주의사항도 표본에 넣는다.

수집 단계의 상태와 검색·답변 품질 평가도 분리하자. 변환 성공률이 높아도 검색에 필요한 문장이 빠지면 사용자 질문에는 답하지 못한다. 대표 질문 몇 개를 정해 원문에서 정답 근거를 찾고, 변환 결과에도 같은 근거가 있는지 비교하는 방식이 유용하다.

토큰 절감률은 과금 영수증이 아니다

새 Analytics와 Logs는 샘플링된 변환 정보를 제공한다. GraphQL의 markdownForAgentsAdaptiveGroups로 최근 7일 데이터를 조회할 수도 있다. 발표에서 말하는 수치에는 샘플 가중치를 적용한 추정 건수와 바이트 기반 토큰 추정치가 포함된다. 분석 기능 안내

문서에 따르면 토큰 추정은 바이트 수를 4로 나눈 뒤 내림하며, 절감 집계에는 조건을 충족한 full 변환만 포함된다. Markdown이 더 크면 절감값이 음수일 수도 있다. 토큰 추정과 집계 범위

운영 보고서에는 다음 세 값을 따로 남기는 것을 권한다.

변환 품질: 결과 코드의 분포와 필수 내용 누락 여부.

전송 크기: 같은 문서의 HTML·Markdown 크기와 요청 시간.

모델 사용량: 실제 사용하는 모델의 토크나이저 또는 API 사용량 응답.

이 셋의 측정 대상과 분모를 적어 두면 ‘평균 크기는 줄었는데 실패 페이지는 늘었다’는 상황을 놓치기 어렵다. 한글·코드·URL이 많은 문서도 따로 표본을 잡자. 바이트 수가 같은 입력이라도 모델 토큰 수가 동일하다고 가정하지 않는 편이 안전하다.

전송 지연은 trace와 클라이언트 기록을 함께 본다

새 tracing은 샘플링된 스트리밍 변환에 markdown_conversion span을 붙이고 변환 결과·바이트·CPU 시간·콘텐츠 제한 플래그를 제공한다. 추적 기능 발표

span의 전체 시간에는 원본 본문 대기와 downstream backpressure가 포함되며 CPU 시간과 다르다. 변환 완료도 클라이언트 수신 완료를 보장하지 않는다. Cloudflare Traces 해석

따라서 지연을 조사할 때는 수집기의 시작·종료·취소 시각과 Ray ID를 함께 보관하는 것이 좋다. 한 요청이 느렸다는 이유만으로 변환기를 병목으로 결론 내리지 말고, 원본 응답 지연과 클라이언트의 읽기 중단을 각각 확인한다. 로그를 공유할 때는 쿠키와 인증 헤더를 제거한다.

도입은 작은 공개 문서 범위부터

변환은 Pro·Business·Enterprise와 SSL for SaaS 고객에게 추가 비용 없이 제공된다. 분석 데이터 접근은 모든 플랜에 열려 있어도 변환 기능이 자동으로 켜지는 것은 아니다. 원본에 Content-Signal이 없으면 ai-train=yes, search=yes, ai-input=yes가 기본 추가되므로 콘텐츠 이용 정책도 먼저 검토한다. 지원 범위와 설정

다음은 실제 도입 전에 수행할 권장 순서다.

공개 문서 중 짧은 안내, 긴 참조 문서, 표·코드가 많은 글을 골라 검수 기준을 만든다.

현재 플랜과 정책을 확인하고, 필요한 경우 특정 경로부터 적용하는 방식을 검토한다.

Playground 결과와 수집기의 실제 GET 결과를 비교한다.

partial·error·unfinished가 나온 페이지는 개별 원인을 확인한다. 상태를 임의로 성공으로 합치지 않는다.

원문 대체 경로와 재수집 기준을 정하고, 변경 전후 대표 질문의 정답 근거를 대조한다.

이번 변화는 Markdown 제공 기능에 운영 관찰 수단이 추가됐다는 데 의미가 있다. 전환 여부는 절감률 한 숫자보다 필수 내용 보존, 실패 처리, 실제 모델 사용량을 함께 보고 판단하는 편이 좋다.

확인 범위

2026년 11월 10일 한국 시간 기준으로 공식 발표·문서와 공개 문서의 GET 응답을 확인했다. 계정 설정 변경, 유료 플랜 전환, API 키 생성, GraphQL 조회, 실제 고객 트래픽의 trace 분석은 수행하지 않았다. 위 도입 절차는 검증 결과가 아닌 실행 권고다.