문서解析 AI 시작하기: PDF, Word, Excel에서 구조화된 데이터 추출 완벽 가이드

업무에서 PDF 계약서, Word 보고서, Excel 데이터 시트를 다루신 적이 있으신가요? 이 파일들에서 필요한 정보를 하나하나 복사해서 정리하는 것이 얼마나 번거로운 일인지 알고 있습니다. 이번 튜토리얼에서는 AI를 활용하여 이 문제를 자동화하는 방법을 알려드리겠습니다.

완전 초보자도 따라할 수 있도록 단계별로 설명드리니 편하게 읽어 주세요.

Claude API란? 왜 문서解析에 유용한가요?

API는 쉽게 말해서 "AI와 대화하는 전화번호"라고 생각하시면 됩니다. 우리가 앱에 메시지를 보내면 답장이 오는 것처럼, 코드에서 Claude에게 문서를 보내면 내용을 이해하고 분석한 결과를 돌려받을 수 있습니다.

Claude API가 문서解析에 뛰어난 이유:

• 한국어 이해력 우수: 한글 문서를 자연스럽게 읽고 분석합니다
• 표 구조 파악: Excel 표나 Word 표를 데이터로 변환합니다
• 논리적 이해: 문서의 맥락과 의미를 파악합니다
• 결과 정렬: 원하는 형태로 구조화하여 출력합니다

HolySheep AI에서 Claude API 키 발급받기

Claude API를 사용하려면 먼저 API 키가 필요합니다. HolySheep AI를 통해 간단하게 발급받을 수 있습니다.

순서:

1. 지금 가입 페이지에 접속합니다
2. 이메일과 비밀번호로 계정을 만듭니다 (해외 신용카드 불필요)
3. 로그인 후 대시보드에서 "API Keys" 메뉴를 클릭합니다
4. "새 키 생성" 버튼을 누르고 키 이름을 입력합니다
5. 화면에 표시되는 키를 복사하여 안전한 곳에 저장합니다

💡 힌트: API 키는 비밀번호와 같습니다. 다른 사람과 공유하지 말고, 코드에 직접 쓰지 말고 환경 변수로 관리하세요.

개발 환경 준비하기

코드 작성을 위해 필요한 도구들을 설치하겠습니다. 처음 접하시는 분들도 걱정 마세요. 하나씩 따라하시면 됩니다.

1단계: Python 설치 확인

터미널(명령 프롬프트)을 열고 다음 명령어를 입력하세요:

python --version

버전 번호가 보이면 이미 설치되어 있습니다. 버전이 안 보이면 Python 공식 사이트에서 다운로드하여 설치하세요.

2단계: 필요한 라이브러리 설치

Python에서 문서를 다루는 데 필요한 도구들을 설치합니다. 터미널에 아래 명령어를 한 줄씩 입력하세요:

pip install python-docx openpyxl pdfplumber anthropic python-dotenv

설치 과정에서 오류가 나면 아래 명령어를 시도하세요:

pip install --user python-docx openpyxl pdfplumber anthropic python-dotenv

3단계: 프로젝트 폴더 만들기

문서解析을 위한 폴더를/desktop/docparser" target="_blank">이 예제처럼 만들어 주세요. 그 안에 다음 파일들을 만들겠습니다:

• apikey.env - API 키를 안전하게 저장하는 파일
• document_analyzer.py - 메인 분석 코드
• sample.pdf, sample.docx, sample.xlsx - 테스트용 문서들

첫 번째 코드: API 연결 확인하기

가장 먼저 HolySheep AI의 Claude API에 정상적으로 연결되는지 확인하는 코드를 작성하겠습니다.

import anthropic
from dotenv import load_dotenv
import os

.env 파일에서 API 키 불러오기
load_dotenv()
api_key = os.getenv("HOLYSHEEP_API_KEY")

HolySheep AI 서버에 연결
client = anthropic.Anthropic(
    api_key=api_key,
    base_url="https://api.holysheep.ai/v1"
)

간단한 테스트 메시지 보내기
message = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=100,
    messages=[
        {"role": "user", "content": "안녕하세요! 연결 테스트입니다. '성공'이라고만 답해주세요."}
    ]
)

print("연결 성공!")
print("AI 응답:", message.content[0].text)

이제 apikey.env 파일에 API 키를 저장하겠습니다:

HOLYSHEEP_API_KEY=sk-your-holysheep-api-key-here

코드 실행 결과로 "연결 성공! AI 응답: 성공"이라고 나오면 정상입니다.

💡 힌트: sk-your-holysheep-api-key-here 부분을 실제 API 키로 교체하세요. 키는 HolySheep AI 대시보드에서 복사할 수 있습니다.

PDF 파일에서 텍스트 추출하기

PDF는 가장 많이 사용하는 문서 형식입니다. pdfplumber 라이브러리를 사용하면 텍스트를 쉽게 추출할 수 있습니다.

import pdfplumber

def extract_text_from_pdf(pdf_path):
    """PDF 파일에서 모든 텍스트 추출"""
    all_text = []
    
    with pdfplumber.open(pdf_path) as pdf:
        print(f"총 {len(pdf.pages)} 페이지의 PDF입니다.")
        for page_num, page in enumerate(pdf.pages, 1):
            text = page.extract_text()
            if text:
                all_text.append(f"[페이지 {page_num}]\n{text}")
    
    return "\n\n".join(all_text)

사용 예시
pdf_text = extract_text_from_pdf("sample.pdf")
print("추출된 텍스트 미리보기:")
print(pdf_text[:500] if pdf_text else "텍스트가 없습니다.")

Word 문서 분석하기

Word 파일(.docx)은 python-docx 라이브러리로 처리합니다. 표와 문단을 모두 읽어보겠습니다.

from docx import Document

def extract_text_from_word(docx_path):
    """Word 문서에서 텍스트와 표 추출"""
    doc = Document(docx_path)
    content = []
    
    for element in doc.element.body:
        if element.tag.endswith('p'):  # 문단(paragraph)
            text = doc.paragraphs[len(content)].text.strip()
            if text:
                content.append({"type": "text", "content": text})
        
        # 표가 있으면 표도 추가
        for table in doc.tables:
            table_data = []
            for row in table.rows:
                row_data = [cell.text.strip() for cell in row.cells]
                table_data.append(" | ".join(row_data))
            if table_data:
                content.append({"type": "table", "content": "\n".join(table_data)})
    
    return content

사용 예시
word_content = extract_text_from_word("sample.docx")
print(f"총 {len(word_content)}개 요소 발견")
for item in word_content[:3]:
    print(f"[{item['type']}]: {item['content'][:100]}...")

Excel 데이터 구조화하기

Excel 파일(.xlsx)은 openpyxl로 읽습니다. 여러 시트와 표 형태 데이터를 깔끔하게 추출합니다.

import openpyxl

def extract_data_from_excel(xlsx_path):
    """Excel 파일에서 모든 시트의 데이터 추출"""
    wb = openpyxl.load_workbook(xlsx_path)
    all_data = {}
    
    for sheet_name in wb.sheetnames:
        sheet = wb[sheet_name]
        rows = []
        
        for row in sheet.iter_rows(values_only=True):
            # 빈 행 제외하고 데이터 수집
            if any(cell is not None for cell in row):
                rows.append([str(cell) if cell is not None else "" for cell in row])
        
        if rows:
            all_data[sheet_name] = rows
    
    return all_data

사용 예시
excel_data = extract_data_from_excel("sample.xlsx")
for sheet_name, data in excel_data.items():
    print(f"\n=== {sheet_name} 시트 ===")
    for row in data[:5]:  # 처음 5행만 표시
        print(" | ".join(row))

실전 프로젝트: 문서 자동 분석기 만들기

이제 위에서 만든 함수들을 결합하여 PDF, Word, Excel을 자동으로 분석하는 도구를 만들겠습니다. Claude AI가 문서의 핵심 내용을 정리해줍니다.

import anthropic
from dotenv import load_dotenv
import os
import pdfplumber
from docx import Document
import openpyxl
import json

load_dotenv()
api_key = os.getenv("HOLYSHEEP_API_KEY")

client = anthropic.Anthropic(
    api_key=api_key,
    base_url="https://api.holysheep.ai/v1"
)

def read_any_document(file_path):
    """모든 문서 형식 읽기"""
    if file_path.endswith('.pdf'):
        with pdfplumber.open(file_path) as pdf:
            return "\n".join(page.extract_text() or "" for page in pdf.pages)
    elif file_path.endswith('.docx'):
        doc = Document(file_path)
        return "\n".join(para.text for para in doc.paragraphs)
    elif file_path.endswith('.xlsx'):
        wb = openpyxl.load_workbook(file_path)
        result = []
        for sheet in wb.sheetnames:
            result.append(f"[{sheet}]")
            for row in wb[sheet].iter_rows(values_only=True):
                if any(cell for cell in row):
                    result.append(" | ".join(str(c) if c else "" for c in row))
        return "\n".join(result)
    else:
        with open(file_path, 'r', encoding='utf-8') as f:
            return f.read()

def analyze_with_claude(document_text, file_name):
    """Claude API로 문서 분석"""
    prompt = f"""다음 문서를 분석해서 주요 정보를 정리해주세요.

파일명: {file_name}

【분석 항목】
1. 문서 종류와 목적
2. 핵심 내용 요약 (3줄 이내)
3. 주요 인물/조직/날짜/금액 등 중요 정보
4. 표나 데이터가 있으면 구조화

문서 내용:
{document_text[:3000]}"""

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=1000,
        messages=[{"role": "user", "content": prompt}]
    )
    
    return response.content[0].text

메인 실행
print("📄 문서 자동 분석기へようこそ!")
print("-" * 40)

files = ["sample.pdf", "sample.docx", "sample.xlsx"]

for file_path in files:
    try:
        print(f"\n📎 {file_path} 분석 중...")
        text = read_any_document(file_path)
        result = analyze_with_claude(text, file_path)
        print(f"\n【{file_path} 분석 결과】")
        print(result)
    except Exception as e:
        print(f"❌ {file_path} 처리 중 오류: {e}")

print("\n✨ 모든 문서 분석 완료!")

자주 발생하는 오류 해결

오류 1: "API 키를 찾을 수 없습니다"

원인: .env 파일을 만들지 않았거나 파일 이름이 다른 경우

해결 방법:

1. 프로젝트 폴더에 "apikey.env" 파일이 있는지 확인하세요
2. 파일 내용 첫 줄에 정확히 이렇게 적었는지 확인하세요: HOLYSHEEP_API_KEY=여기에_키_적기
3. 코드 첫 줄에 load_dotenv()가 있는지 확인하세요

오류 2: "Cannot connect to host"

원인: base_url이 잘못되었거나 네트워크 문제

해결 방법:

1. base_url이 정확히 https://api.holysheep.ai/v1인지 확인하세요
2. openai.com이나 anthropic.com으로 되어 있으면 HolySheep 주소로 수정하세요
3. 인터넷 연결이 정상인지 확인하세요

오류 3: "No module named 'pdfplumber'"

원인: 라이브러리가 설치되지 않음

해결 방법:

pip install pdfplumber python-docx openpyxl

여전히 안 되면:

pip install --user pdfplumber python-docx openpyxl

오류 4: "Document is empty" 또는 텍스트가 안 나옴

원인: PDF가 이미지 스캔본이거나 문서에 텍스트가 없는 경우

해결 방법:

• PDF가 스캔된 이미지라면 OCR(문자 인식) 도구가 필요합니다
• pytesseract 라이브러리를 추가로 설치하세요
• Word/Excel 파일은 Microsoft Word나 Excel에서 열어서 텍스트가 보이는지 확인하세요

오류 5: "Rate limit exceeded"

원인: 너무 많은 요청을 빠르게 보냄

해결 방법:

• 요청 사이에 time.sleep(1)을 추가하세요
• HolySheep AI 대시보드에서 사용량과 할당량을 확인하세요
• 여유 크레딧이 있는지 확인하세요

응용 아이디어

여기까지 따라오시느ة 수고하셨습니다. 이제 더 고급인 활용법을 알려드리겠습니다.

• 계약서 분석기: PDF 계약서를 업로드하면 주요 조항과 위험 항목을 자동으로 추출
• 보고서 요약기: 여러 개의 Word 보고서를 한 번에 분석하여 핵심 포인트를 정리
• 재무 데이터 추출: Excel 재무제표에서 매출, 비용, 이익 등을 자동으로 수집
• 명함 관리: 이미지 PDF 명함에서 연락처 정보를 추출하여 데이터베이스화

정리하며

이번 튜토리얼에서는:

• HolySheep AI에서 Claude API 키를 발급받는 방법
• PDF, Word, Excel 파일에서 텍스트를 추출하는 방법
• 추출한 문서를 Claude AI가 분석하도록 하는 방법
• 자주 발생하는 오류들을 해결하는 방법

을 배웠습니다. 이 기본 구조를 응용하면 다양한 문서 처리 자동화를 만들 수 있습니다.

HolySheep AI의 단일 API 키로 Claude뿐만 아니라 GPT, Gemini, DeepSeek 등 다양한 AI 모델도同一个 키로 사용할 수 있습니다. 필요에 따라 모델을 바꿔가며 테스트해보세요!

不明한 점이 있으면 HolySheep AI 웹사이트의 문서나 고객 지원을 이용해주세요. Happy coding!