OSH AI Hub
개발·운영: 연세대학교 산업보건연구소 소속 Team SHIELD (Safety & Health Information Evolutionary Linked Database).
산업안전보건 데이터·AI 플랫폼의 첫 구현입니다. 현재는 독립적인 디자인 프리뷰와 공개 합성 샘플 API입니다.
실행
시스템 Node 20을 변경하지 않고 프로젝트 안에 Node 24를 설치합니다. npm 스크립트는 프로젝트 런타임을 사용합니다.
cd /home/shield/osh-ai-hub
npm ci
npm run dev
브라우저: http://localhost:3100
원격 서버에서는 VS Code의 Ports 기능으로 3100을 전달하거나 SSH 포트 포워딩을 사용하세요. 기존 사이트의 3000, 8600~8602, 3838 포트는 사용하지 않습니다. 개발·미리보기 서버는 기본적으로 127.0.0.1에만 바인딩합니다.
프로덕션 빌드 미리보기:
npm run build
npm start
구현된 기능
- 반응형 메인, 분야 탐색, 검색·필터·정렬과 URL 상태
- 12개 DEMO 자료의 상세·변수 설명·미리보기·CSV 다운로드
- 실제 샘플 카탈로그·데이터 API, 매개변수 검사, SHA256 다운로드 헤더
- Python·R·curl 문서, 코드 복사, 브라우저 API 실행, OpenAPI JSON
- 모델 목록·카드, 기존 분석 도구 소개 (연결 준비 중), 로컬 이미지 미리보기
- Google OAuth 시작·콜백 연결 코드와 미설정 안내
- API 키·사용량 화면 미리보기, 오류·404·빈 상태
- FastAPI liveness/readiness 기본 서비스
- 자료·버전·파일·역할·RLS 초기 SQL 마이그레이션
아직 운영 기능이 아닌 부분
Google 로그인·내 계정·세션 갱신·로그아웃을 구현했습니다. 외부 Google/Supabase/Vercel 설정 및 실계정 통합 검증은 필요합니다. 약관 동의·관리자 MFA는 후속 구현입니다. 현재 API 키 화면은 인증된 사용자 정보를 조회하지 않으며 키를 만들지 않습니다.
DB migration은 작성된 초안이며 연결된 Supabase에서 실행·검증하지 않았습니다. 현재 웹 카탈로그는 web/lib/catalog.ts를 읽습니다. 데이터 적재·관리자 CRUD·저장소 대용량 업로드·서명 다운로드·개인 API 키·호출 제한·사용량·실제 모델 추론은 후속 단계입니다.
샘플 CSV는 수 KB의 합성 fixture이므로 웹에서 생성합니다. 운영 대용량 파일은 별도 object storage로 직접 전송해야 합니다. 모든 예제는 DEMO이며 실제 기관 자료나 검증된 모델 성능이 아닙니다.
디자인 가이드
다른 앱과 색상·폰트·버튼·박스를 통일하려면 OSH Family Design을 사용하세요. 공통 CSS·예시 화면과 폰트를 포함한 전달용 ZIP을 만들 수 있습니다.
새 DEMO AI와 도구 화면은 공통 디자인 가이드를 기준으로 만들고, 디자인 브리프 양식으로 화면 구성을 공유합니다.
새 데이터 패키지를 준비할 때
협업자는 공개 데이터 제작 가이드에서 양식 ZIP을 받을 수 있습니다. 문서 변경 후 python3 scripts/export-opendata-kit.py로 공개 묶음과 해시를 갱신합니다. 이 작은 ZIP은 문서·합성 양식만 담으며 실제 연구자료는 포함하지 않습니다.
다른 서버·AI에서 자료를 제작해 전달하려면 OpenData 제작·인수 가이드를 먼저 읽으세요. 복사 가능한 패키지 템플릿과 다른 AI에게 전달할 작업 지시문을 제공합니다. 실제 원본은 Git에 올리지 않으며 자료 소개·3행 미리보기·검색 DEMO·다운로드를 각각 검토하고 연결합니다. 폴더 복사만으로 웹에 자동 등록되지는 않습니다.
구조
web/: Next.js App Router, TypeScript, CSS 디자인 시스템, 로컬 한글 글꼴ai-api/: Python/FastAPI 독립 서비스supabase/migrations/: 데이터 구조와 RLS 초안docs/: 조사, 프로젝트 설정, 다음 작업compose.yaml: loopback 8100의 AI 서비스
DEMO 배포
이번 공개는 Supabase 연결 없이 진행합니다. Vercel의 Root Directory는 web, Production Branch는 main입니다. 기본 로그인은 비활성화되어 있으며, 기존 분석 앱도 연결하지 않습니다. 환경변수 없이 디자인·샘플 다운로드·API를 사용할 수 있습니다.
Google 로그인과 배포
새 Supabase·Vercel·Google 프로젝트 설정을 먼저 읽으세요.
기존 프로젝트를 재사용하지 않습니다. 비밀 키는 저장소와 채팅에 넣지 않습니다.
실제 로그인은 후속 통합 완료 후 ENABLE_GOOGLE_AUTH=true로 명시적으로 켭니다. 환경변수는 web/.env.example에 있습니다. 실제 값은 web/.env.local에만 넣습니다. 인증 설정이 없어도 모든 공개 디자인 화면과 샘플 API를 실행할 수 있습니다.
검사
npm run lint
npm run typecheck
npm test
npm run build
npm run test:e2e
브라우저 설치:
./node_modules/node/bin/node ./node_modules/@playwright/test/cli.js install chromium
E2E는 인증 환경변수가 없는 디자인 프리뷰를 기준으로 하며 Google 실계정 인증 성공을 주장하지 않습니다. 3101 포트에 독립적인 테스트 서버를 실행하므로, 3100의 기존 미리보기 서버를 재사용하지 않습니다.
AI 서비스
Gemini 키 저장 위치와 로컬 모델의 역할은 로컬 AI 설정을 참고하세요.
cd ai-api
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ruff check .
.venv/bin/pytest
.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8100
GET /health는 프로세스 상태를 반환합니다. 실제 모델이 없으므로 GET /ready와 POST /inference/v1/image는 503을 반환합니다.
저장소 루트에서 docker compose config --quiet로 설정을 검사하고 docker compose up --build -d로 실행할 수 있습니다. Docker 데몬 사용 권한이 필요합니다.
데이터베이스
새 개발 Supabase 프로젝트에서 마이그레이션을 검토한 뒤 적용합니다. 이미 사용 중인 DB에는 적용하지 않습니다. 초기 정책은 공개된 자료만 읽을 수 있고, 일반 사용자는 자신의 프로필만 수정할 수 있습니다. 역할·자료 쓰기와 private bucket 접근은 기본적으로 허용하지 않습니다.
현재 상태와 다음 단계를 참고하세요.
산재 판정사례 · 7개 질환군
산재 컬렉션 /datasets/sanje에서 COPD·뇌심혈관·암·감염성질환·난청·근골격계·기타 자료를 안내합니다. 2026-09-19.v1은 중복 없는 61,566건이며 COPD는 2,049건입니다. 연구자: 윤진하 · 연세대학교 산업보건연구소. 기존 COPD 소개·DEMO 주소는 유지합니다.
실제 검색·원문·라벨·근무시간과 질환별 8종 파일은 기존 인증 관문 뒤에서 제공합니다. 검색은 로컬 임베딩과 한국어 키워드를 결합한 자연어 하이브리드를 기본으로 하고, 원문 키워드 검색·다중 필터도 제공합니다. 검색 범위·인덱스·검증 방법을 참고하세요. 데이터 인수·화면·다운로드·버전 전환·검증 기록을 참고하세요.
이전 COPD 검토 DEMO (교체 전 기록)
실제 COPD 자료를 사용하는 별도 검토 앱을 /demo/copd/에 연결한다. 키워드·로컬/Gemini 임베딩 검색, 원문·측정자료 확인, 로컬 Gemma 설명을 구현했다. 공개 합성 샘플과 구분하며 .3 Basic 인증 뒤에서 제공한다. 자료 배포·다운로드와 검색·답변 품질 평가는 완료되지 않았다.
공통 관문 설정·UFW 요청, 로컬 AI와 서비스 운영, 데이터 검토를 참고한다. .3 nginx 및 Vercel 최종 경로는 적용 후 검증이 필요하다.
실제 데이터와 음성 안내
홈과 데이터 목록은 산재 판정사례 컬렉션과 7개 질환 소개를 공개한다. OSH Family Design과 데이터 제작 가이드는 협업의 협업 템플릿에서 제공한다. 합성 예제 카드는 관리자에게만 표시하며 개발자 샘플 API는 DEMO 상태로 유지한다. COPD 원본은 Supabase private Storage에 업로드했고 기존 인증 관문 뒤에서 다운로드한다. 다운로드 구성을 참고한다.
Supabase Storage·Google 로그인 설정, 음성 안내 설계·예산 제한·검증 상태를 참고한다. 음성 DEMO는 /demo/voice/이며 OpenAI 크레딧 부족으로 실제 음성 생성 검증 대기 중이다. 카드도 관리자에게만 표시한다.
2026-09-19 Google 로그인
로그인 화면·보안 설계, 외부 콘솔 설정.
Google 로그인은 계정 인증이며 기존 연구자료의 접근 관문을 대체하지 않습니다. 실계정 검증 전 인증 완료를 주장하지 않습니다.
설정된 로그인 UI와 PKCE 시작 경로의 추가 E2E: npm run test:e2e --workspace web -- --config playwright.auth.config.ts (실계정 인증 없이 DEMO 설정 사용).
OSHMASTER 표준분류 마스터
/datasets/oshmaster에서 자료 소개와 실제 코드 3행 미리보기를 제공합니다. /demo/oshmaster/는 기존 인증 관문 뒤에서 표준명·동의어·판본별 계층을 탐색하고 선택 코드 JSON 및 원본 ZIP을 제공합니다. 원 코드 98,638개이며 사건 자료와 별도 데이터셋입니다. 화면·권한·Storage·검증 및 한계를 참고하세요. 정적 앱 빌드는 npm run build:oshmaster-demo --workspace web입니다.
KOSHA GUIDE 그래프 검색
/datasets/kosha-guide-graphrag에서 기술지침 658건의 본문 18,659구간을 가공한 자료를 소개하고, /demo/kosha-guide-graphrag/에서 현장 말로 검색합니다. 낱말 검색은 패키지의 BM25 색인·통제어휘 확장에 의미(벡터) 채널을 RRF로 합친 것이고(질의 벡터는 루프백 임베딩 서비스 osh-embed, ai-api/embed_service.py, Qwen3-Embedding-4B CPU), 선택한 발췌와 조문만 근거로 Claude(Sonnet 5.5)가 짧게 답합니다. 맥락 검색(ai-api/app/kosha_context.py)은 질문을 Claude가 개념으로 풀어 지식 그래프(1단계 패키지 추출 + 2단계 Claude Batch 추출 ai-api/scripts/graphrag/)와 커뮤니티 보고서·지침 발췌·조문을 모은 뒤 근거를 인용해 답합니다. 자료는 NAS kosha-guide-graphrag/serving/current에 있고 관문이 다이제스트로 고정합니다. 2026-10-06 소유자 결정으로 공개했고(KOSHA GUIDE 이용 허락 확인), 인계 패키지 전체 zip과 핵심 zip을 비공개 Storage 서명 주소로 내려받습니다. 인수 검토, 화면 설계. 화면 빌드는 npm run build:kosha-guide-graphrag-demo --workspace web입니다.
산업안전 판례 · 유사어휘
같은 날 들어온 두 인계 패키지는 제작자의 참조 앱(FastAPI + Jinja2, 읽기 전용)을 ai-api/app/safetybread_apps.py가 NAS serving/current에서 그대로 관문에 올립니다(/demo/osh-precedents/, /demo/osh-synonym-vocab/, 의미검색 꺼짐, 배포본 다이제스트 고정, 패키지의 파일 링크는 Storage 서명 주소로 넘김). 소개는 /datasets/osh-precedents, /datasets/osh-synonym-vocab. 판례 배포본 v2는 소유자 지시로 본문에 남아 있던 이름 표기 4종을 지운 판본입니다. 세 자료의 다운로드 파일은 python ai-api/scripts/upload_safetybread_storage.py <slug>로 자료별 비공개 버킷에 올리고 local_asset/<slug>-storage-manifest.json이 만들어져야 열립니다. 판례 인수 검토, 유사어휘 인수 검토.
