CrewMeal 설치 · 구성 · 테스트 가이드
CrewMeal을 처음 접하는 담당자가 위에서부터 순서대로 따라 하기만 하면 설치 · 구성 · 테스트를 끝낼 수 있도록 만든 문서입니다. 모든 명령은 Windows PowerShell 기준이며, 코드 상자의 복사 버튼을 눌러 그대로 붙여 넣으면 됩니다.
이 파일 하나만 있으면 인터넷 없이도 볼 수 있습니다. 체크한 진행 상황은 이 브라우저에 저장됩니다.
먼저 트랙을 고르세요
CrewMeal 테스트는 세 단계로 나뉩니다. A → B → C 순서를 권장합니다. 트랙 A는 혼자서 바로 할 수 있고, 트랙 C는 트랙 B의 배포 주소가 있어야 진행할 수 있습니다.
SharePoint · Copilot 연동
라이브러리에서 버튼 한 번 → Copilot이 그 내용을 근거로 답하는 전 과정.
- 필요
- M365 테넌트 관리자
- 시간
- 1일
- 비용
- 사용량 과금
제품 개요와 아키텍처는 GitHub 저장소와 소개 사이트를 참고하세요.
사전 준비 사항
시작하기 전에 미리 준비해 두어야 할 것을 한곳에 모았습니다. 고른 트랙에 해당하는 것만 준비하면 됩니다. 표에서 — 는 필요 없다는 뜻입니다.
1-1. 한눈에 보는 준비물
| 준비물 | A | B | C | 비고 |
|---|---|---|---|---|
| 작업용 Windows PC (PowerShell) | ✅ | ✅ | ✅ | 1대 |
| Python 3.11 이상 | ✅ | ✅ | ✅ | 3.12 권장 |
| Git | ✅ | ✅ | ✅ | 소스 내려받기 |
| 비민감 테스트 문서 | ✅ | ✅ | ✅ | 5~10개 |
| Azure 구독 (소유자) | — | ✅ | ✅ | 결제 수단 등록됨 |
| Azure CLI · Azure Developer CLI | — | ✅ | ✅ | 배포 도구 |
| Entra 앱 등록 + 관리자 동의 권한 | — | ✅ | ✅ | 앱 1개 |
| eastus2 모델 쿼터 1,150K TPM | — | ✅ | ✅ | 부족하면 배포 실패 |
| Microsoft 365 테넌트 | — | — | ✅ | 테스트 사이트 생성 가능 |
| SharePoint 앱 카탈로그 | — | — | ✅ | 없으면 먼저 생성 |
| Node.js 22.14 이상 23 미만 | — | — | ✅ | SPFx 빌드용 |
| Microsoft 365 Copilot 라이선스 | — | — | ✅ | 마지막 검증 1건에만 |
remoteBuild)되므로 로컬 Docker가 필요 없고,
PPTX 변환용 LibreOffice와 한글 문서용 rhwp는 서버 이미지에 이미 포함되어 있습니다.
트랙 A는 AI를 쓰지 않는 저품질(텍스트+OCR) 티어로 도는 덕분에 둘 다 필요 없습니다.
1-2. 누가 참여해야 하나요
한 사람이 모든 권한을 갖고 있다면 혼자서도 가능합니다. 보통은 아래 세 역할이 필요합니다.
테스트 실무 담당자
문서를 준비하고 결과 품질을 평가하는 주 담당자입니다.
- 권한
- 본인 PC에 프로그램 설치
- 할 일
- 설치 · 실행 · 결과 확인
- 시간
- 약 30분
Azure 담당자
고객사 구독에 리소스를 만들고 배포를 실행합니다.
- 권한
- 구독 소유자(Owner)
- 할 일
- 쿼터 확인 ·
azd up - 시간
- 반나절
Microsoft 365 관리자
앱 동의와 SharePoint 설정을 처리합니다.
- 권한
- 테넌트 관리자 · 사이트 소유자
- 할 일
- 동의 · 앱 설치 · API 승인
- 시간
- 1일
1-3. 설치할 소프트웨어
| 프로그램 | 필요 버전 | 필요한 트랙 | 확인 명령 |
|---|---|---|---|
| Python | 3.11 이상 (3.12 권장) | A · B · C | python --version |
| Git | 최신 | A · B · C | git --version |
설치는 winget으로 한 번에 할 수 있습니다. 필요한 줄만 실행하세요.
# 모든 트랙 공통
winget install Python.Python.3.12
winget install Git.Git
# 트랙 B 이상
winget install Microsoft.AzureCLI
winget install Microsoft.Azdnvm-windows로 버전을 전환해 사용하세요.
설치가 끝났으면 아래로 한 번에 확인합니다. 필요한 줄에서 버전이 나오면 준비 완료입니다.
python --version
git --version
az version --output tsv 2>$null
azd version
node --version1-4. Azure 쪽 준비 트랙 B · C
1-5. Microsoft 365 쪽 준비 트랙 C
1-6. 테스트용 문서 준비
아래 종류를 섞어서 5~10개 준비하면 뒤의 테스트 시나리오를 그대로 수행할 수 있습니다.
| 문서 종류 | 확인하는 것 | 필요한 트랙 |
|---|---|---|
| 텍스트 위주 PPTX | 원문 문장이 보존되는지 | A |
| 표가 들어간 PPTX | 행·열 값이 누락 없이 재현되는지 | A |
1-7. 네트워크 · 방화벽
사내망에서 아래 주소가 막혀 있으면 설치나 배포가 중간에 멈춥니다. 폐쇄망이라면 미리 방화벽 예외를 신청해 두세요.
| 접속 대상 | 용도 | 트랙 |
|---|---|---|
github.com | 소스 코드 내려받기 | A · B · C |
pypi.org, files.pythonhosted.org | 파이썬 패키지 설치 | A · B · C |
127.0.0.1:8000 | 트랙 A 로컬 웹 서버 (외부 통신 아님) | A |
1-8. 시작 전 최종 점검
체크가 모두 켜지면 준비 완료입니다. 체크 상태는 이 브라우저에 저장됩니다.
| 점검 항목 | 트랙 | |
|---|---|---|
| 어느 트랙까지 진행할지 정했다 (A / B / C) | 공통 | |
| Python과 Git이 설치되어 버전이 확인된다 | 공통 | |
| 비민감 테스트 문서를 5~10개 모았다 | 공통 |
테스트 시나리오와 합격 기준
고객사 검증 회의에서 그대로 쓸 수 있는 체크리스트입니다. 체크 상태는 자동 저장됩니다.
| # | 시나리오 | 조작 | 합격 기준 | 트랙 | |
|---|---|---|---|---|---|
| 1 | 기본 텍스트 추출 | 텍스트 위주 PPT 업로드 | 원문 문장이 결과 HTML에 보존됨 | A | |
| 2 | 표 추출 | 표가 있는 PPT | 표의 행/열 값이 누락 없이 재현 | A | |
| 3 | 차트 해석 | 막대/선 차트 슬라이드 | 그래프가 무엇을 뜻하는지 문장으로 설명 | B | |
| 4 | 간트차트 | 일정표 슬라이드 | 작업명·기간·순서가 문장으로 설명 | B | |
| 5 | PDF 처리 | 스캔 아닌 PDF | 페이지별 내용이 추출됨 | B | |
| 6 | HWP/HWPX | 한글 문서 | 본문·표·머리말/꼬리말 추출 | B | |
| 7 | 대용량 | 50장 이상 덱 | 실패 없이 완료, 소요 시간 기록 | B | |
| 8 | 재작업 | 상태 페이지 → 다시 실행 | 새 결과로 갱신 | B | |
| 9 | 피드백 반영 | 상태 페이지 → 코멘트 후 재작업 | 코멘트가 반영된 결과 | B | |
| 10 | 원본 무결성 | 처리 후 원본 다운로드 | 원본 파일이 변경되지 않음 | C | |
| 11 | 권한 | 권한 없는 사용자로 접근 | 상태 페이지 접근 차단 | C | |
| 12 | 삭제 | 검색강화 삭제 | 색인/컬럼에서 제거, 상태 NotEnabled | C | |
| 13 | 검색 반영 | canary 검색 | 원본 문서가 결과에 노출 | C | |
| 14 | Copilot 답변 | 범위 지정 질의 | 강화 내용을 근거로 답변 | C | |
| 15 | 비용 확인 | 관리자 대시보드 | 문서별 토큰·추정 비용 표시 | B |
환경 변수 총정리
필수
| 변수 | 설명 | 예시 |
|---|---|---|
CREWMEAL_M365_TENANT_ID | Entra 테넌트 ID | GUID |
CREWMEAL_M365_CLIENT_ID | 앱 클라이언트 ID | GUID |
CREWMEAL_M365_CLIENT_SECRET | 앱 시크릿 | (비밀) |
CREWMEAL_M365_SITE_ID | SharePoint 사이트 ID | host,guid,guid |
CREWMEAL_M365_DRIVE_ID | 문서 라이브러리 드라이브 ID | |
CREWMEAL_M365_LIST_ID | 목록 ID | GUID |
CREWMEAL_M365_SITE_URL | 사이트 URL | https://.../sites/... |
CREWMEAL_ADMIN_KEY | 관리자 포털 키 | (비밀) |
CREWMEAL_WEB_SESSION_SECRET | 세션 서명 키 | (비밀) |
선택 / 튜닝
| 변수 | 기본값 | 설명 |
|---|---|---|
PPTX_ANALYSIS_TIER | vision | vision(고품질) / text_ocr(무비용) |
PPTX_OCR_ENABLED | true | 저품질 티어에서 이미지 OCR 사용 |
SLIDE_IMAGE_MODEL | gpt-5.6-luna | gpt-5.2, gpt-5-mini 선택 가능 |
SLIDE_IMAGE_DEPLOYMENT | gpt-5-6-luna-test | Foundry 배포 이름 |
SLIDE_IMAGE_RENDER_DPI | 144 | 페이지 렌더 해상도 |
SLIDE_IMAGE_MAX_WORKERS | 2 | 동시 분석 슬라이드 수 |
CREWMEAL_INGEST_REQUIRE_AUTH | true | Ingest API 토큰 검증 |
CREWMEAL_STATUS_REQUIRE_AUTH | 위 값과 동일 | 상태 페이지 Entra 로그인 |
CREWMEAL_INGEST_ALLOWED_ORIGINS | (없음) | CORS 허용 오리진(CSV) |
CREWMEAL_ARTIFACT_BACKEND | 자동 | database / blob / 로컬 파일 |
SOFFICE_PATH | 자동 탐색 | 로컬 LibreOffice 경로 |
RHWP_PATH | 자동 탐색 | 로컬 rhwp 경로 |
CREWMEAL_MIP_SDK_CLI | (없음) | MIP 복호화 CLI (README 참고) |
문제 해결
| 증상 | 원인 | 해결 |
|---|---|---|
ConfigurationError: Missing Microsoft 365 settings | 워커 실행 창에 M365 변수 없음 | 같은 창에서 변수 설정 후 재실행 (트랙 A는 더미 값 사용) |
웹 시작 시 CREWMEAL_WEB_SESSION_SECRET must be set | 인증 켠 상태에서 세션 키 없음 | 세션 시크릿 설정 또는 CREWMEAL_INGEST_REQUIRE_AUTH=false |
로그인 시 AADSTS50011 | 리디렉션 URI 미등록 | B-5 수행 ({웹주소}/auth/callback 추가 + ID 토큰 허용) |
웹 앱이 기동 실패 (ConfigurationError) | CREWMEAL_STATUS_REQUIRE_AUTH=true 인데 SSO 자격증명 없음 | M365 변수 3종 설정 또는 해당 값을 false |
SPFx 버튼에서 Failed to fetch | CORS 미설정 | CREWMEAL_INGEST_ALLOWED_ORIGINS 에 SharePoint 오리진 추가 후 재배포 |
| Graph 403 오류 | 사이트 권한 미부여 | scripts\grant_test_site_permission.ps1 실행 |
| 스크립트가 “Missing user environment variable” | $env: 로만 설정 | C-3처럼 User 범위로 설정 후 새 창에서 실행 |
azd up 이 쿼터 오류로 실패 | 모델 TPM 부족 | infra/modules/foundry.bicep 의 capacity 값 축소 |
| 리전 오류 | location 이 eastus2 로 고정 | infra/main.bicep 의 @allowed 목록 수정 |
상태가 계속 Queued | 워커 미실행 | 로컬은 cli once, Azure는 워커 앱 상태 확인 |
| 결과에 그림 설명이 없음 | 저품질 티어 | /admin/settings?tab=analysis 에서 분석 티어를 고품질로 변경 후 재작업 |
| 한글 OCR이 깨짐 | 기본 OCR 모델은 한국어 미지원 | 로컬은 PPTX_OCR_REC_MODEL/PPTX_OCR_REC_KEYS 지정, 컨테이너는 --build-arg ENABLE_LOW_TIER_OCR=1 로 한국어 모델 포함해 빌드 |
| MIP 문서 처리 실패 | 복호화 미구성 | README 「MIP 복호화」 참고, 관리 포털의 준비 마법사로 점검 |
| 검색에 반영되지 않음 | 재인덱싱 안 함 | 라이브러리 설정에서 수동 재인덱싱 후 대기 |
로그 확인
# 웹 앱 로그
az containerapp logs show -g <리소스그룹> -n <웹앱이름> --tail 100
# 워커 로그
az containerapp logs show -g <리소스그룹> -n <워커앱이름> --tail 100비용 관리와 정리
- 문서별 추정 비용은 관리자 대시보드와 상태 페이지에 표시됩니다.
- 비용을 아예 쓰지 않으려면 분석 티어를 저품질(text_ocr) 로 두세요.
- PoC 구성은 야간 비용 절감을 위해 PostgreSQL이 자동 정지되고, 매일 아침 (한국시간 기준, 기본 07시) Logic App이 자동 재시작합니다. 워커는 DB 연결이 끊긴 동안 재시도하며 스스로 복구합니다.
cd $HOME\CrewMeal
azd down --purge --force추가 정리:
- SharePoint 테스트 사이트에서 앱 제거, App Catalog에서 패키지 삭제
- Entra 앱 등록 삭제
- 커넥터 방식이었다면 Copilot 커넥터 연결 삭제
보안 · 데이터 취급
고객사 보안 검토에서 자주 나오는 질문에 대한 답입니다.
- 원본 문서는 임시 폴더에만 내려받고 처리 후 삭제합니다.
- 원본 파일 바이너리는 수정하지 않습니다.
- 원본 문서 · PDF · PNG · HTML 본문과 비밀 값은 로컬 상태 DB에 저장하지 않습니다.
- Azure OpenAI · Blob 접근은 API 키 없이 관리 ID(
DefaultAzureCredential)로 인증합니다. - SharePoint 접근 권한은
Sites.Selected로 지정한 사이트에만 부여됩니다. - 컬럼 방식은 원본 문서의 권한을 그대로 따르므로 권한 복제가 없습니다.
- PoC는 공개 엔드포인트를 사용하므로 기밀 문서를 넣지 마세요.
도움 요청 시 함께 보내주세요
문제가 해결되지 않으면 아래 정보를 정리해 전달해 주세요. 훨씬 빨리 원인을 찾을 수 있습니다.
- 어느 트랙(A/B/C)의 몇 번 단계인지
- 실행한 명령과 화면에 나온 오류 메시지 전문
azd env get-values결과 (비밀 값은 반드시 가리고)- 상태 페이지의 실패 단계 이름과 메시지
- 컨테이너 앱 로그 마지막 100줄