2026년 11월 7일 GitHub Trending(Python)에 pipeshub-ai/pipeshub-ai가 올랐습니다. 이 글 작성 시점 GitHub API 기준 스타 4,034·forks 650, 최신 릴리스 v1.0.0(2026-10-27), 기본 브랜치 HEAD 699b8b5(2026-11-07), 라이선스 Apache-2.0. 포지셔닝은 “워크플레이스 챗봇”이 아니라 회사 지식의 권한 인식 컨텍스트 층(context layer)입니다. Slack·Drive·Jira·Confluence·GitHub·M365 등 50+ 소스를 동기화하고, 사람 검색 UI와 에이전트(MCP/SDK/API)가 같은 권한 경계 안에서 인용 가능한 답을 쓰게 합니다.
이 글은 초보 튜토리얼이 아닙니다. 에이전트 루프 vs 단발 RAG, Compose 프로파일(slim/full)·저장소 역할 분리, MCP 14도구·Python SDK(pipeshub_sdk.Pipeshub 2.0.1) 표면, EnterpriseRAG-Bench 리더보드 CSV로 재확인한 #1(93.24), v1.0.0 브레이킹 체인지, 그리고 이 박스에서 Docker 없이 통과한 패키지 실측을 실무자 기준으로 정리합니다. 오늘 오전 Opensource 딥다이브(google/skills, 절차서 카탈로그)와는 계층이 다릅니다 — 저쪽은 에이전트에게 어떻게 할지를 꽂고, 이쪽은 무엇을 볼 권한이 있는지를 꽂습니다.
한 줄 정의와 핵심 숫자
PipesHub는 커넥터가 소스+ACL을 끌어오면 인덱싱 파이프라인(파싱·청크·임베딩)과 지식 그래프가 레코드·사람·티켓·PR·스레드를 잇고, 질의는 단일 retrieve-then-generate가 아니라 에이전트 루프로 도구를 반복 호출합니다. 모든 도구 호출은 요청자 권한으로 필터되고, 답은 블록 단위 인용을 붙입니다.
| 항목 | 값 (이 글 검증) |
|---|---|
| 저장소 | pipeshub-ai/pipeshub-ai |
| 릴리스 / HEAD | v1.0.0 (2026-10-27) / main@699b8b5 (2026-11-07) |
| 라이선스 | Apache-2.0 (루트 LICENSE · PyPI pipeshub-sdk · npm MCP 패키지) |
| 스타 / forks / open issues | 4,034 / 650 / 224 (GitHub API 2026-11-07) |
| 토픽 | agentic-rag, context-layer, mcp, graphrag, enterprise-search, self-hosted … |
| Python SDK | pipeshub-sdk 2.0.1 (import pipeshub_sdk, 클래스 Pipeshub) |
| MCP 패키지 | @pipeshub-ai/mcp 4.10.0 (bin: mcp / pipeshub) |
| 문서·클라우드 | docs.pipeshub.com · app.pipeshub.com/mcp |
왜 ‘컨텍스트 층’인가: 절차서·브라우저·워크트리와의 계층
에이전트 스택에서 역할이 겹치면 운영 비용이 폭증합니다. 오늘 오전 google/skills는 GCP 절차서 카탈로그이고, 어제 worktrunk는 병렬 worktree UX, agent-browser는 AXTree 조작입니다. PipesHub는 그 아래에서 권한 있는 회사 지식을 공급합니다. 코딩 에이전트가 “빌링 워커 재시도 로직이 왜 바뀌었나?”를 물으면 인시던트 포스트모템·PR·슬랙·설계 문서를 그 사용자가 볼 수 있는 범위에서 인용합니다.
| 계층 | 대표 도구 | 에이전트에게 주는 것 | 권한 모델 |
|---|---|---|---|
| 절차서/스킬 | google/skills | CLI·클라우드 작업 순서 | 스킬 작성자 가드레일 |
| 브라우저 런타임 | agent-browser | 페이지 AXTree·@ref | 세션/쿠키 |
| 저장소 슬롯 | worktrunk | 브랜치별 worktree | 로컬 git ACL |
| 회사 지식 층 | PipesHub | 검색·인용·KG·MCP 도구 | 소스 ACL → 요청자 필터 |
| 모델/추론 | BYOM / Ollama | 임베딩·생성 | 테넌트가 키/엔드포인트 소유 |
질의 경로: 에이전트 루프 4도구
README가 명시하는 루프는 계획 → 도구 → 결과 읽기 → 증거 충분할 때까지 반복입니다. 단발 벡터 top-k에 의존하지 않는 이유가 벤치와 연결됩니다.
| 도구 | 역할 | 실패 모드를 막는 지점 |
|---|---|---|
| Hybrid search | 의미+키워드 동시 | 고유명사·에러 문자열 누락 |
| Grep / pattern | 티켓키·심볼·정확한 ID | 임베딩 유사도만의 오탐 |
| Knowledge-graph nav | 문서↔사람↔티켓↔PR 링크 | 청크 고립으로 맥락 단절 |
| Document reading | 매칭 청크가 아니라 원문 개방 | 부분 인용으로 인한 환각 |
모든 호출은 “묻는 사용자”의 권한으로 필터됩니다. MCP/SDK로 붙인 코딩 에이전트도 Personal Access Token이 그 사람으로 동작하므로, client_credentials 서비스 계정과는 경계가 다릅니다(v1.0.0에서 앱 신원에 서비스 계정 바인딩이 강제된 이유와 맞닿습니다).
벤치마크: 숫자와 출처를 분리해서 읽기
README 표와 Hugging Face Space의 leaderboard.csv를 이 박스에서 재확인했습니다. EnterpriseRAG-Bench(Onyx 독립 실행, 50만+ 문서·500문항)에서 PipesHub 93.24로 39개 시스템 중 1위. 비교 열: OpenAI File Search 61.03, Amazon Q 48.96, Azure AI Search 48.42, Vertex AI Search 41.87(README 인용). FRAMES 92.7%(18개 표준 RAG 대비 최고 78.9%)와 “회사 인덱스 vs 앱별 MCP” 비교는 PipesHub 팀 자체 실행이므로 독립 벤치와 무게를 나누어 해석해야 합니다.
| 벤치 | 측정 | 결과 | 실행 주체 |
|---|---|---|---|
| EnterpriseRAG-Bench | 회사 문서 QA | #1 / 39, 93.24 (CSV 재확인) | Onyx (독립) |
| Google FRAMES (824) | 다문서 사실 | 92.7% vs 표준 RAG 최고 78.9% | PipesHub 팀 |
| 회사 인덱스 vs per-app MCP | 100 업무 질문 | Haiku 55→80%, Sonnet 65→89%, Opus 85→92%; 27–45% 빠름 | PipesHub 팀 |
| Code graph accuracy | 9개 저장소 관계 F1 | 8/9에서 최고 | PipesHub 팀 |
리더보드 CSV 헤더: model,overall_score,correctness,completeness,recall,invalid_extra_docs. PipesHub 행은 95.0 / 95.63 / 96.33 / 0.4. “자사 리더보드 1위”가 아니라 외부 Space 스냅샷으로 교차 확인한 점이 실무 평가에 중요합니다.
아키텍처: 3평면 + 저장소 백엔드
FAQ 기술 스택을 기준으로 나눕니다. 웹(Next.js)·API(Node.js)·Python 서비스(커넥터·인덱싱·질의)가 BYOM 임베딩/LLM을 호출합니다. 데이터는 지식 그래프(기본 Neo4j, 대안 ArangoDB), 벡터(Qdrant), MongoDB, 캐시(Redis), 파일(디스크/오브젝트)에 갈라집니다. 로컬은 Redis 스트림, 대규모는 Kafka 프로파일입니다.
| 평면 | 구현 | 책임 |
|---|---|---|
| Web | frontend/ (Next.js, Electron 빌드 자산 포함) | 검색·채팅·관리 UI |
| API | backend/nodejs | 계정·권한·KB·파일·OAuth/PAT |
| Python services | backend/python | 커넥터 동기화·파싱·질의 에이전트 |
| Graph | Neo4j 5.26 / ArangoDB 3.12 | 엔티티·관계 탐색 |
| Vector | Qdrant v1.15 | 시맨틱 검색 |
| KV / Broker | Redis · (옵션) etcd · Kafka | 캐시·작업 큐 |
배포: 원커맨드 설치와 Compose 프로파일
curl -fsSL https://get.pipeshub.com/install | bash는 래퍼입니다. 저장소 루트 install.sh(5,413 B, 이 박스에서 raw·get.pipeshub.com 바이트 일치)는 로직이 거의 없고, 실제 설치는 deployment/docker-compose/install.sh로 위임합니다. standalone 모드는 사전 빌드 이미지만 받고, --build는 풀 클론이 필요합니다. Compose 주석 기준 항상 켜지는 축은 pipeshub-ai·redis·mongodb·qdrant입니다.
| 프로파일 | 컨테이너 | 앱 쪽 변수 | 언제 |
|---|---|---|---|
| (항상) | pipeshub-ai, redis, mongo, qdrant | — | slim 기본 |
| graph-neo4j | neo4j:5.26.0 | DATA_STORE=neo4j | 기본 그래프 |
| graph-arango | arangodb:3.12.4 | DATA_STORE=arangodb | 대안 그래프 |
| kv-etcd | etcd v3.5.17 | KV_STORE_TYPE=etcd | 분산 KV |
| broker-kafka | zk+kafka 7.9.0 | MESSAGE_BROKER=kafka | 대규모 큐 |
| sandbox | sandbox + docker-socket-proxy | SANDBOX_MODE=docker | 코드 실행 아티팩트 |
| search-searxng / fetch-crawl4ai | searxng / crawl4ai | 워크스페이스 설정 | 웹 검색·JS 페이지 |
주의: COMPOSE_PROFILES를 CLI로 넘기면 .env 값을 덮어 프로파일이 빠질 수 있습니다(compose 주석). 클라우드 HTTP-only는 브라우저가 일부 요청을 막아 흰 화면이 난다고 README가 못 박습니다 — TLS 종료(Cloudflare/Nginx/Traefik)가 운영 기본값입니다. Helm은 v1.0.0부터 Qdrant API 키 기본값을 제거했습니다.
MCP·CLI·SDK 표면
에이전트 연결의 실무 기본값은 PAT + MCP입니다. npm @pipeshub-ai/mcp@4.10.0(tgz ~6.29 MB)는 mcp start|serve와 pipeshub CLI를 같이 싣습니다. 도구 파일 기준 이름 14개:
| MCP 도구 | 의도 |
|---|---|
| pipeshub_search | 벡터/시맨틱 검색 |
| pipeshub_chat | 그라운디드 Q&A |
| pipeshub_sources | 소스·모델 디스커버리 |
| pipeshub_get_record_content / preview / download | 레코드 본문·미리보기·원본 |
| pipeshub_show_citations | 인용 UI/증거 |
| pipeshub_agents | 조직 에이전트 목록 |
| pipeshub_directory | 사람·그룹·팀 조회 |
| pipeshub_create_collection / upload / indexing_status | 컬렉션 적재 파이프 |
| pipeshub_connect_source / add_web_source | 커넥터·웹 크롤 등록 |
CLI(pipeshub)는 init·login·search·ask·mcp install --client claude-code|cursor|codex|gemini|claude-desktop까지 한 바이너리에 묶습니다. 클라우드 엔드포인트는 https://app.pipeshub.com/mcp.
Python SDK 2.0.1은 Speakeasy 생성 스타일로, 진입 클래스가 Pipeshub(대소문자 주의: PipesHub가 아님)입니다. 인스턴스 리소스: semantic_search, conversations, agents, knowledge_base, connector*, personal_access_tokens, web_search 등. connector.navigate_knowledge_graph가 SDK에 노출된 점은 README의 KG 네비게이션과 코드 표면이 맞닿는 지점입니다.
| 패키지 | 버전 | 설치/진입 | 의존성 메모 |
|---|---|---|---|
| pipeshub-sdk (PyPI) | 2.0.1 | import pipeshub_sdk → Pipeshub |
httpx, httpcore, pydantic |
| @pipeshub-ai/sdk (npm) | 2.0.1 | TS 클라이언트 | API 대칭 |
| @pipeshub-ai/mcp | 4.10.0 | mcp start --transport stdio|sse |
@modelcontextprotocol/sdk, express, zod, bun |
| pipeshub-sdk-go | 별도 레포 | Go 클라이언트 | README 배지 |
박스 실측 (2026-11-07 KST)
이 박스에는 Docker가 없어 Compose 풀스택은 돌리지 않았습니다. 대신 배포 스크립트·Compose 선언·SDK/MCP 패키지를 실측했습니다.
| 항목 | 결과 |
|---|---|
| install.sh (repo raw vs get.pipeshub.com) | 5,413 B 일치 · 위임형 래퍼 확인 |
| docker-compose.yml (v1.0.0 태그) | 39,249 B · always-on 4 + 프로파일 카탈로그 파싱 |
| pipeshub-sdk 2.0.1 venv 설치·import | import ≈0.10s · 서브모듈 31 · 클래스 Pipeshub |
| Pipeshub 리소스 표면 | semantic_search / conversations / agents / connector.navigate_knowledge_graph 등 |
| @pipeshub-ai/mcp 4.10.0 pack | tgz 6,288,484 B · mcp --help 0.192s · CLI help 0.288s |
| MCP 도구 파일 | pipeshub_*.js 14종 이름 확인 |
| EnterpriseRAG CSV | PipesHub 93.24 행 재확인 (HF Space raw) |
| 미실행 | docker compose up · 실커넥터 동기화 · 실질의 지연 |
저장소 구조와 커넥터 규약
루트는 backend/(db·nodejs·python), frontend/, deployment/, docs/, integrations/, AGENTS.md·CONNECTOR.md 중심입니다. 커넥터 문서는 코딩 에이전트 우선으로 읽기 순서를 강제합니다: high-level → low-level → decisions → intake → step-by-step → permissions → errors → testing → checklist. 핵심 규칙 요약: (1) 소스 ACL과 보이게 맞출 것(불확실하면 숨김), (2) graph/vector/broker 클라이언트를 커넥터에 직접 넣지 말 것, (3) asyncio 루프를 막지 말 것, (4) 시크릿을 로그하지 말 것, (5) 실패한 읽기를 빈 집합으로 쓰지 말 것.
| 경로 | 역할 |
|---|---|
| backend/nodejs | 계정·권한·KB API |
| backend/python | 커넥터·인덱싱·질의 에이전트 |
| frontend/ | Next.js 앱 (+ Electron 패키징 자산) |
| deployment/docker-compose/ | install.sh · compose · env.template · 프로파일 |
| docs/connectors/01–08 | 커넥터 설계·권한·테스트 게이트 |
| CONNECTOR_CHECKLIST.md | PR DoD |
| .claude/skills/add-connector | 커넥터 추가 스킬(에이전트용) |
v1.0.0 업그레이드 함정
릴리스 노트 기준 브레이킹: SAML·generic OAuth 로그인 제거, client_credentials 앱은 서비스 계정 명시 바인딩 필요, Helm Qdrant API 키 필수, POST /connectors/:id/filters 폐기. 기본값으로 Targeted Retrieval·Timeline Summaries 등이 켜지는 변경도 있습니다. 프로덕션 업그레이드 전 IdP·서비스 계정·Helm values를 체크리스트로 고정하세요.
포지셔닝과 도입 판단
PipesHub를 고를 조건은 “모델이 부족해서”가 아니라 “도구별 MCP를 병렬로 붙이면 권한·인용·중복 검색 비용이 폭발해서”인 경우가 많습니다. 자체 벤치의 per-app MCP 대비 회사 인덱스 이득(정확도·지연·토큰)이 그 가설을 뒷받침하지만, 독립 벤치는 EnterpriseRAG 쪽을 우선 보세요. 반대로 단일 SaaS 검색만 필요하고 소스 ACL을 IdP에 맡길 수 있다면 관리형 검색이 운영 단순성에서 이길 수 있습니다. 자기호스팅+BYOM이 계약 조건이라면 Apache-2.0 풀스택은 협상 카드가 됩니다.
| 상황 | PipesHub 적합도 | 대안 쪽 |
|---|---|---|
| 멀티 소스 + 소스 ACL 유지 + 에이전트 MCP | 높음 | 앱별 MCP 나열은 권한 누수·비용 |
| GPU 추론 최적화만 필요 | 낮음 | TensorRT-LLM 등 서빙 스택 |
| 절차서/클라우드 CLI 가드레일 | 계층 다름 | google/skills |
| 로컬 음성 TTS/ASR | 계층 다름 | VibeVoice 등 |
| 관리형만, 인프라 제로 | Cloud 티어 | 또는 Glean급 SaaS |
실무 체크리스트
| 단계 | 확인 |
|---|---|
| 1 | install 스크립트를 파이프 전에 파일로 받아 diff/less |
| 2 | slim으로 기동 → Neo4j/Qdrant/Mongo 헬스 → HTTPS 종료 |
| 3 | 커넥터 1개(이상적으로 GitHub 또는 Drive) + ACL 스모크 계정 2명 |
| 4 | PAT 발급 → pipeshub mcp install --client … 또는 Cloud MCP URL |
| 5 | 같은 질문을 UI·MCP·SDK 세 경로로 던져 인용·권한 일치 확인 |
| 6 | v1.0.0이면 IdP/서비스 계정/Helm Qdrant 키 마이그레이션 |
| 7 | Kafka/etcd/sandbox는 트래픽·코드실행 요구가 생길 때 프로파일 추가 |
요약하면, pipeshub-ai/pipeshub-ai v1.0.0은 “또 하나의 RAG 데모”가 아니라 권한 경계가 코드화되어 있는 회사 지식 런타임에 가깝습니다. 오늘 트렌딩에서 고른 이유도 그 계층이 오전 skills 카탈로그·어제의 worktree/브라우저 런타임과 겹치지 않기 때문입니다. 박스에서는 Docker 부재로 풀스택 기동 대신 SDK·MCP·Compose·리더보드 CSV를 교차 검증했습니다 — 프로덕션 채택 전엔 반드시 자체 테넌트에서 이중 계정 ACL 스모크를 통과시키세요.