문서를 마크다운으로 변환
markitdown-for-ai Docker 이미지를 사용하여 문서를 Markdown으로 변환합니다. 로컬 Python 설치가 필요 없으며, 전적으로 Docker 내에서 실행됩니다.
필수 조건
⚠️ 이 스킬을 사용하려면 시스템에 Docker 또는 Podman이 설치되어 있어야 합니다. 사용하기 전에 Docker Desktop 또는 Podman이 실행 중인지 확인하세요.
빠른 명령어
이 스킬은 기본적으로 Docker를 사용합니다. Docker를 사용할 수 없으면 자동으로 Podman을 시도합니다.
stdin (파이프) 사용:
# 먼저 Docker 시도
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < file.pdf
# Docker를 사용할 수 없으면 Podman 사용:
podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < file.pdf
로컬 파일 사용 (현재 디렉토리 마운트):
# 먼저 Docker 시도
docker run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest file.docx
# Docker를 사용할 수 없으면 Podman 사용:
podman run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest file.docx
출력을 파일로 저장:
# 먼저 Docker 시도
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < input.pptx > output.md
# Docker를 사용할 수 없으면 Podman 사용:
podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < input.pptx > output.md
cat 사용하여 파이프:
# 먼저 Docker 시도
cat file.xlsx | docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest
# Docker를 사용할 수 없으면 Podman 사용:
cat file.xlsx | podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest
지원 형식
| 형식 | 확장자 |
|---|---|
.pdf | |
| Word | .docx |
| PowerPoint | .pptx |
| Excel | .xlsx |
| HTML | .html |
이미지 다운로드 (최초 한 번)
docker pull ghcr.io/opentechil/markitdown-for-ai:latest
에이전트 워크플로우
사용자가 읽거나 분석할 문서 파일을 제공하면 다음과 같이 진행하세요:
- Docker를 사용할 수 있는지 확인하고, 없으면 Podman을 시도합니다 (스킬이 자동으로 대체)
- 위의 변환 명령어를 실행합니다
- stdout을 Markdown 콘텐츠로 캡처합니다
- Markdown을 직접 읽고 분석합니다 — 임시 파일이 필요 없습니다
예시 — 사용자가 "이 PDF를 요약해줘"라고 말한 경우:
# markdown을 셸 변수에 캡처하거나 다음 단계로 직접 파이프
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < report.pdf
# Docker가 실패하면 Podman 시도:
podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < report.pdf
이 스킬을 사용해야 하는 경우
문서에서 콘텐츠를 추출하거나 처리해야 할 때마다 이 스킬을 사용하세요. 일반적인 시나리오는 다음과 같습니다:
문서 변환 및 추출
-
DOCX 파일 읽기: "이 Word 문서를 읽어줘", "docx에서 텍스트 추출"
docker run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest document.docx # Docker를 사용할 수 없으면 Podman 사용: podman run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest document.docx -
PDF 파일 읽기: "PDF를 마크다운으로 변환", "PDF 콘텐츠 추출"
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < report.pdf # 또는 Podman 사용: podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < report.pdf -
PowerPoint 처리: "pptx에서 슬라이드 추출", "프레젠테이션 변환"
docker run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest slides.pptx # 또는 Podman 사용: podman run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest slides.pptx -
Excel 데이터 추출: "스프레드시트 읽기", "xlsx를 마크다운으로 변환"
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < data.xlsx # 또는 Podman 사용: podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < data.xlsx -
HTML 스크래핑: "웹 페이지를 마크다운으로 변환", "기사 콘텐츠 추출"
docker run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest page.html # 또는 Podman 사용: podman run --rm -v "$(pwd):/data" -w /data ghcr.io/opentechil/markitdown-for-ai:latest page.html
AI 및 자동화 사용 사례
-
문서 요약: "이 PDF/보고서/문서를 요약해줘" — 먼저 마크다운으로 변환한 후 추출된 콘텐츠를 요약에 사용
content=$(docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < document.pdf) # Docker가 실패하면 Podman 시도: content=$(podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < document.pdf) # 그런 다음 $content를 요약 프롬프트에 전달 -
계약서/계약 분석: "이 PDF에서 주요 조건을 추출해줘", "계약서 읽기"
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < contract.pdf # 또는 Podman 사용: podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < contract.pdf -
업로드된 파일 처리: 사용자가 분석을 위해 문서를 업로드할 때 — 먼저 변환한 후 마크다운을 분석합니다
-
일괄 문서 처리: 인덱싱 또는 분석을 위해 여러 파일을 루프로 변환
for f in *.pdf; do docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < "$f" > "${f%.pdf}.md" # 필요시 Podman도 시도: # podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < "$f" > "${f%.pdf}.md" done -
RAG/임베딩 파이프라인: "벡터 저장소용 문서 준비" — 문서를 마크다운으로 변환하여 청크 및 임베딩
docker run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < document.pdf | text-embeddings-cli embed # 또는 Podman 사용: podman run --rm -i ghcr.io/opentechil/markitdown-for-ai:latest < document.pdf | text-embeddings-cli embed
예시
| 사용자 요청 | 작업 |
|---|---|
| "이 PDF를 읽어줘" | PDF를 마크다운으로 변환하고 콘텐츠 표시 |
| "이 Word 문서에 뭐가 들어있니?" | DOCX를 마크다운으로 변환하고 요약 |
| "이 Excel 파일에서 표를 추출해줘" | XLSX 변환 — 표가 마크다운 형식으로 유지 |
| "이 웹페이지를 마크다운으로 변환해줘" | HTML을 마크다운으로 변환 |
| "프레젠테이션 요약해줘" | PPTX 슬라이드를 마크다운으로 변환 |
일반적인 실수
| 실수 | 해결 방법 |
|---|---|
{owner} 플레이스홀더 사용 | ghcr.io/opentechil/markitdown-for-ai:latest 사용 |
stdin용 -i 플래그 누락 | 파이프 시 항상 -i 추가 |
| 잘못된 경로 마운트 | $(pwd)와 -w /data를 함께 사용 |
| 마운트 없이 Docker가 상대 경로를 찾을 것으로 예상 | -v "$(pwd):/data"로 마운트 |
Docker vs Podman
이 스킬은 Docker와 Podman을 모두 지원합니다. 환경에 따라 선택하세요:
Docker를 사용해야 하는 경우
- 개발 워크스테이션 - macOS/Windows의 Docker Desktop
- 프로덕션 서버 - Docker Engine이 있는 Linux 시스템
- 대부분의 사용 사례 - 완전한 기능 패리티, 더 쉬운 설정
Podman을 사용해야 하는 경우
- 루트리스 컨테이너 - 더 나은 보안 및 격리
- Docker가 없는 Linux 서버 - 데몬이 필요 없음
- 클라우드 네이티브 환경 - Kubernetes 및 컨테이너 오케스트레이션과 호환
- 보안 규정 준수 - 루트 권한 없이 실행
올바른 명령어 선택
위의 예시는 Docker 및 Podman 명령어를 모두 제공합니다. 스킬은 Docker를 먼저 시도할 것을 권장합니다. "명령어를 찾을 수 없음" 또는 기타 실행 오류가 발생하면 Podman 명령어를 대신 사용하세요.
Docker와 Podman은 동일한 이미지(ghcr.io/opentechil/markitdown-for-ai:latest)를 공유하므로 docker와 podman을 제외한 명령어는 동일합니다.
사용 가능 여부 확인
어떤 컨테이너 런타임이 설치되어 있는지 확인하세요:
# Docker 확인
docker --version
# Podman 확인
podman --version
Docker를 사용할 수 없으면 Podman을 직접 대체하여 사용할 수 있습니다.
이미지 다운로드 (최초 한 번 설정)
Docker와 Podman은 동일한 레지스트리를 공유하므로 다운로드 명령어는 동일합니다:
docker pull ghcr.io/opentechil/markitdown-for-ai:latest
podman pull ghcr.io/opentechil/markitdown-for-ai:latest
선호하는 런타임으로 한 번 다운로드하면 두 런타임 모두 로컬 이미지에 액세스할 수 있습니다.