Skip to content

Commit cb26137

Browse files
wkdgus1164claude
wkdgus1164
and
claude
committed
docs: 전체 문서에 parameter 테이블 추가
- CLI 가이드: 명령줄 옵션 테이블 추가 - Python API 가이드: 사용 패턴별 테이블 추가 - LangChain 가이드: 청킹 매개변수 가이드 테이블 추가 - 포맷 문서 (HWP/HWPX/PDF): 지원 기능 비교 테이블 추가 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent bc68899 commit cb26137

6 files changed

Lines changed: 120 additions & 31 deletions

File tree

‎docs/formats/hwp.md‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -111,15 +111,25 @@ for chunk in chunks:
111111

112112
자세한 내용은 [Python API 가이드](../guides/python-api.md)와 [LangChain 연동 가이드](../guides/langchain.md)를 참고하세요.
113113

114-
## 제한사항
115-
116-
현재 버전에서는 다음 기능을 지원하지 않아요.
117-
118-
- 이미지 추출 (대체 텍스트만 표시)
119-
- 도형 및 차트
120-
- 머리글/바닥글
121-
- 각주/미주
122-
- 복잡한 표 병합 구조
114+
## 지원 기능
115+
116+
다음은 HWP 포맷에서 지원하는 기능과 제한사항이에요.
117+
118+
| 기능 | 상태 | 설명 |
119+
|------|------|------|
120+
| 텍스트 추출 | ✅ | 유니코드 텍스트를 완전히 지원해요 |
121+
| 문단 구조 | ✅ | 문단 단위로 구조화해서 추출해요 |
122+
| 제목 인식 | ✅ | 스타일 기반으로 제목 레벨을 자동 인식해요 |
123+
| 표 추출 | ⚠️ | 기본 표 구조를 지원하지만, 복잡한 병합 구조는 제한적이에요 |
124+
| 리스트 | ✅ | 순서 있는/없는 리스트를 지원해요 |
125+
| 메타데이터 | ✅ | 작성자, 제목, 생성 일시 등을 추출해요 |
126+
| 이미지 | ❌ | 이미지 추출은 지원하지 않아요 (대체 텍스트만 표시) |
127+
| 도형/차트 | ❌ | 도형과 차트는 지원하지 않아요 |
128+
| 머리글/바닥글 | ❌ | 머리글과 바닥글은 추출하지 않아요 |
129+
| 각주/미주 | ❌ | 각주와 미주는 지원하지 않아요 |
130+
131+
!!! warning "표 병합 제한"
132+
복잡한 셀 병합이 있는 표는 제대로 추출되지 않을 수 있어요. 간단한 행/열 병합은 지원해요.
123133

124134
## 다음 단계
125135

‎docs/formats/hwpx.md‎

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -134,16 +134,26 @@ for chunk in chunks:
134134

135135
자세한 내용은 [Python API 가이드](../guides/python-api.md)와 [LangChain 연동 가이드](../guides/langchain.md)를 참고하세요.
136136

137-
## 제한사항
138-
139-
현재 버전에서는 다음 기능을 지원하지 않아요.
140-
141-
- 이미지 추출 (대체 텍스트만 표시)
142-
- 도형 및 차트
143-
- 머리글/바닥글
144-
- 각주/미주
145-
- 복잡한 표 병합 구조
146-
- 수식 (한글 수식 편집기)
137+
## 지원 기능
138+
139+
다음은 HWPX 포맷에서 지원하는 기능과 제한사항이에요.
140+
141+
| 기능 | 상태 | 설명 |
142+
|------|------|------|
143+
| 텍스트 추출 | ✅ | XML 기반으로 텍스트를 정확하게 추출해요 |
144+
| 문단 구조 | ✅ | 문단 단위로 구조화해서 추출해요 |
145+
| 제목 인식 | ✅ | 스타일 기반으로 제목 레벨을 자동 인식해요 |
146+
| 표 추출 | ⚠️ | 기본 표 구조를 지원하지만, 복잡한 병합 구조는 제한적이에요 |
147+
| 리스트 | ✅ | 순서 있는/없는 리스트를 지원해요 |
148+
| 메타데이터 | ✅ | 작성자, 제목, 생성 일시 등을 추출해요 |
149+
| 이미지 | ❌ | 이미지 추출은 지원하지 않아요 (대체 텍스트만 표시) |
150+
| 도형/차트 | ❌ | 도형과 차트는 지원하지 않아요 |
151+
| 머리글/바닥글 | ❌ | 머리글과 바닥글은 추출하지 않아요 |
152+
| 각주/미주 | ❌ | 각주와 미주는 지원하지 않아요 |
153+
| 수식 | ❌ | 한글 수식 편집기로 작성된 수식은 지원하지 않아요 |
154+
155+
!!! info "HWP보다 정확한 파싱"
156+
HWPX는 XML 기반이라 HWP 바이너리보다 파싱이 더 정확하고 안정적이에요.
147157

148158
## 다음 단계
149159

‎docs/formats/pdf.md‎

Lines changed: 20 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -123,15 +123,26 @@ for chunk in chunks:
123123

124124
자세한 내용은 [Python API 가이드](../guides/python-api.md)와 [LangChain 연동 가이드](../guides/langchain.md)를 참고하세요.
125125

126-
## 제한사항
127-
128-
현재 버전에서는 다음 기능을 지원하지 않아요.
129-
130-
- 이미지 추출 (텍스트만 추출)
131-
- 표 구조 인식 (텍스트로만 추출)
132-
- 수식 (LaTeX 등)
133-
- 주석 및 하이라이트
134-
- 복잡한 레이아웃 (다단 구성 등)
126+
## 지원 기능
127+
128+
다음은 PDF 포맷에서 지원하는 기능과 제한사항이에요.
129+
130+
| 기능 | 상태 | 설명 |
131+
|------|------|------|
132+
| 텍스트 추출 | ✅ | 페이지별로 텍스트를 추출해요 |
133+
| 문단 구조 | ⚠️ | 빈 줄을 기준으로 문단을 구분해요 (레이아웃에 따라 부정확할 수 있어요) |
134+
| 제목 인식 | ❌ | PDF는 제목 정보를 명시적으로 포함하지 않아 자동 인식이 어려워요 |
135+
| 표 추출 | ❌ | 표 구조를 인식하지 못하고 텍스트로만 추출돼요 |
136+
| 리스트 | ⚠️ | 리스트 마커를 텍스트로 추출하지만 구조화하지는 않아요 |
137+
| 메타데이터 | ✅ | 제목, 작성자, 생성 도구 등을 추출해요 |
138+
| 이미지 | ❌ | 이미지 추출은 지원하지 않아요 |
139+
| 도형/차트 | ❌ | 도형과 차트는 지원하지 않아요 |
140+
| 수식 | ❌ | LaTeX 등의 수식은 지원하지 않아요 |
141+
| 주석/하이라이트 | ❌ | PDF 주석과 하이라이트는 추출하지 않아요 |
142+
| 다단 레이아웃 | ❌ | 복잡한 다단 구성은 텍스트 순서가 올바르지 않을 수 있어요 |
143+
144+
!!! warning "레이아웃 제한"
145+
PDF는 페이지 레이아웃 정보가 명확하지 않아서, 복잡한 구조의 문서는 텍스트 추출 순서가 올바르지 않을 수 있어요.
135146

136147
## 다음 단계
137148

‎docs/guides/cli.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,16 @@ uv run ureca_document_parser 보고서.hwp > 출력.md
3333

3434
## 옵션
3535

36+
### 명령줄 옵션 요약
37+
38+
| 옵션 | 설명 | 예시 |
39+
|------|------|------|
40+
| `input_file` | 변환할 입력 파일 경로 (필수) | `보고서.hwp` |
41+
| `-o`, `--output` | 출력 파일 경로 (미지정 시 표준 출력) | `-o 보고서.md` |
42+
| `-f`, `--format` | 출력 형식 (기본값: `markdown`) | `-f markdown` |
43+
| `--list-formats` | 지원하는 입력/출력 형식 목록 출력 | `--list-formats` |
44+
| `--help` | 도움말 메시지 출력 | `--help` |
45+
3646
### 출력 포맷 지정
3747

3848
`-f` 또는 `--format` 옵션으로 출력 포맷을 지정할 수 있어요. 현재는 `markdown`만 지원해요.

‎docs/guides/langchain.md‎

Lines changed: 32 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,38 @@ for chunk in chunks:
3636
- `chunk_size` (선택, 기본값 1000): 각 청크의 최대 문자 수
3737
- `chunk_overlap` (선택, 기본값 200): 인접 청크 간 중복 문자 수
3838

39-
!!! tip "chunk_size와 chunk_overlap 설정"
40-
- **chunk_size**: 임베딩 모델의 최대 토큰 수에 맞춰 설정하세요. 일반적으로 500~2000 사이가 적당해요.
41-
- **chunk_overlap**: chunk_size의 10~20%가 적당해요. 문맥 연속성을 유지하는 데 도움이 돼요.
39+
### 청킹 매개변수 가이드
40+
41+
| 매개변수 | 기본값 | 권장값 | 설명 |
42+
|---------|--------|--------|------|
43+
| `chunk_size` | 1000 | 500~2000 | 각 청크의 최대 문자 수예요. 임베딩 모델의 최대 토큰 수를 고려해서 설정하세요. |
44+
| `chunk_overlap` | 200 | chunk_size의 10~20% | 인접 청크 간 중복 문자 수예요. 문맥 연속성을 유지해서 검색 품질을 높여요. |
45+
46+
!!! tip "매개변수 선택 가이드"
47+
**chunk_size 선택하기:**
48+
49+
- **짧은 청크 (500~800)**: 정확한 정보 검색에 유리해요. 특정 수치나 용어를 찾을 때 적합해요.
50+
- **중간 청크 (1000~1500)**: 범용적으로 사용하기 좋아요. 문맥과 정확성의 균형이 적당해요.
51+
- **긴 청크 (1500~2000)**: 긴 문맥이 필요한 요약이나 분석에 적합해요. 단, 임베딩 모델의 토큰 제한을 확인하세요.
52+
53+
**chunk_overlap 선택하기:**
54+
55+
- **작은 중복 (10%)**: 처리 속도와 저장 공간이 중요할 때 사용해요.
56+
- **중간 중복 (15~20%)**: 일반적인 RAG 파이프라인에 적합해요. 문장이나 단락이 청크 경계에서 잘리는 것을 방지해요.
57+
- **큰 중복 (20~30%)**: 매우 긴밀한 문맥 연결이 필요할 때 사용하지만, 중복 정보가 많아질 수 있어요.
58+
59+
**사용 예시:**
60+
61+
```python
62+
# 짧은 FAQ 문서: 정확한 답변 검색
63+
chunks = convert("FAQ.hwp", chunks=True, chunk_size=600, chunk_overlap=60)
64+
65+
# 긴 보고서: 문맥 기반 질의응답
66+
chunks = convert("보고서.hwp", chunks=True, chunk_size=1500, chunk_overlap=300)
67+
68+
# 기술 문서: 균형잡힌 설정
69+
chunks = convert("매뉴얼.hwp", chunks=True, chunk_size=1000, chunk_overlap=200)
70+
```
4271

4372
## 실전 예시
4473

‎docs/guides/python-api.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,25 @@ processed = markdown.replace("구버전", "신버전")
4848
convert("보고서.hwp", "보고서.md", format="markdown")
4949
```
5050

51+
## 사용 패턴 요약
52+
53+
`convert()` 함수는 매개변수 조합에 따라 다양한 방식으로 사용할 수 있어요. 상황에 맞는 패턴을 선택하세요.
54+
55+
| 용도 | 코드 예시 | 반환값 |
56+
|------|----------|--------|
57+
| **파일로 바로 저장** | `convert("보고서.hwp", "보고서.md")` | `None` |
58+
| **문자열로 받아서 처리** | `markdown = convert("보고서.hwp")` | `str` (Markdown 텍스트) |
59+
| **여러 파일 결합** | `md = convert("part1.hwp")`<br>`combined = md + convert("part2.hwp")` | `str` |
60+
| **파싱 후 조건부 저장** | `md = convert("문서.hwp")`<br>`if "키워드" in md:`<br>` Path("out.md").write_text(md)` | `str` |
61+
| **포맷 명시** | `convert("문서.hwp", "문서.md", format="markdown")` | `None` |
62+
| **디렉토리 자동 생성** | `convert("문서.hwp", "a/b/c/문서.md")` | `None` (경로 자동 생성) |
63+
64+
!!! tip "반환값 타입 구분하기"
65+
- `output_path`를 지정하면 → **파일 저장** + `None` 반환
66+
- `output_path`를 생략하면 → **문자열 반환** (`str`)
67+
68+
문자열로 받으면 추가 처리가 가능하고, 파일로 저장하면 코드가 간결해져요.
69+
5170
## 실전 예시
5271

5372
### 여러 파일 일괄 변환

0 commit comments

Comments
 (0)