代码摄入系统
  
多语言矢量数据库流水线 -一个全面的系统，用于将代码存储库摄取、解析和矢量化到可搜索的矢量数据库中。
🎯 这是什么？
一个生产就绪的代码摄取管道，它：
- 克隆 GitHub 仓库
- 作语法分析 多语言代码库（Rust、TypeScript、Solidity、文档）
- 派遣 使用最先进的嵌入模型的代码块
- 商店 Qdrant中用于语义搜索的向量
- 监视器 摄取质量和性能
主要特点
- 📂 多存储库支持 -通过基于优先级的处理克隆和摄取多个存储库
- 🔍 多语言解析 -基于AST的Rust、TypeScript、Solidity和Markdown解析
- 🧠 语义嵌入 -Qwen3-Embedded-8B（4096D）通过DeepInfra
- 💾 向量存储 -Qdrant具有特定语言的集合（本地Docker或云）
- 🐳 Docker Compose -使用Qdrant完成本地设置以进行开发
- 🔎 跨语言搜索 -在所有摄入的代码库中进行语义搜索
- 📊 综合监控 -统计、健康检查和质量验证
- 🔄 检查点恢复 -从上次成功状态恢复中断的摄取
- ⚡ 批处理 -具有速率限制的并发嵌入生成
🚀 快速开始
运行代码摄取系统的主要方法是 Docker Compose。您可以在一个命令中获得Qdrant、摄入和MCP服务器。
先决条件
使用Docker Compose运行
# Clone the repository
git clone git@github.com:oikonai/code-ingest.git
cd code-ingest
# Configure environment
cp .env.example .env
# Edit .env and set:
# DEEPINFRA_API_KEY=your_key
# GITHUB_TOKEN=your_pat_token # for private repos
# Start all services (Qdrant + Ingestion + MCP)
docker compose up这就开始了 Qdrant （端口6333），运行 完全摄入 （克隆/刷新repos、解析、嵌入、存储），然后打开 MCP服务器 （端口8001）。准备就绪时：
# Check health
curl http://localhost:8001/health
# Access Qdrant dashboard
open http://localhost:6333/dashboard服务:
- Qdrant （6333）：具有web UI的本地矢量数据库
- 摄入：一次完全重新摄入，然后退出
- MCP服务器 （8001）：查询接口和健康端点
看 用于选项（例如，不重新摄入运行、优先级过滤器、故障排除）。
替代方案：本地Python
要在没有Docker的情况下运行（例如使用Qdrant Cloud）：
# Clone and setup
git clone git@github.com:oikonai/code-ingest.git
cd code-ingest
make setup
# Configure .env (Qdrant, DeepInfra, GitHub token)
cp .env.example .env
# Edit .env, then:
source .venv/bin/activate
make check-env
# Ingest and search
make ingest
make ingest-search QUERY='authentication service'
make health需要Python 3.11+和 紫外线 （由自动安装 make setup).
🗄️ 矢量后端配置
系统支持两个矢量数据库后端：
Qdrant（云/远程）
对于云部署或托管向量数据库：
# .env configuration for Qdrant Cloud (optional)
# If not set, uses local Docker Qdrant instance
QDRANT_URL=https://your-cluster.cloud.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key部署选项:
- 本地Docker （默认）：无需配置，使用
http://qdrant:6333 - Qdrant云：设置
QDRANT_URL和QDRANT_API_KEY在.env - 本地Python：设置
QDRANT_URL=http://localhost:6333（不需要API密钥）
⚙️ 配置存储库
系统从以下位置加载存储库配置 config/repositories.yaml。此文件定义了要摄取的存储库及其属性。
存储库配置文件
编辑 config/repositories.yaml 添加、删除或修改存储库：
repos_base_dir: ./repos
repositories:
- id: my-repo
github_url: https://github.com/myorg/my-repo
repo_type: backend # frontend|backend|middleware|mcp_server|infrastructure|tool|documentation
languages:
- rust
- typescript
components:
- api
- lib
has_helm: true
helm_path: helm/
service_dependencies:
- other-service
exposes_apis: true
api_base_path: /api/myservice
priority: high # high|medium|low配置选项
- repos_base_dir：克隆存储库的基本目录（默认：
./repos) - ID：存储库的唯一标识符
- github url：完整的GitHub存储库URL
- repo_type：存储库类型（影响集合分配）
- 语言：存储库中存在的语言列表
- 组件：要索引的关键目录/组件
- has_helm：repo是否包含Helm charts
- 头盔路径：仓库中Helm图表的路径
- 服务依赖性：此回购所依赖的服务列表
- 展览\_ pis：repo是否公开API
- api_base_path：API的基本路径
- 优先：处理优先级（高|中|低）
环境变量覆盖
您可以覆盖配置文件路径：
export REPOSITORIES_CONFIG=/path/to/custom-repos.yaml
make ingest📁 项目结构
code-ingest/
├── 📖 Makefile # Comprehensive command interface
├── 📝 CLAUDE.md # Development guidelines & best practices
├── 🐳 docker-compose.yml # Local Docker Compose setup
├── 🐳 Dockerfile.ingest # Ingestion service Docker image
├── 🐳 Dockerfile.mcp # MCP server Docker image
├── 📦 config/
│ ├── repositories.yaml # Repository configuration
│ └── collections.yaml # Collection name mappings
├── 🐳 docker/
│ ├── README.md # Docker Compose documentation
│ ├── entrypoint-ingest.sh # Ingestion service entrypoint
│ └── entrypoint-mcp.sh # MCP server entrypoint
├── 🔌 mcp/
│ ├── server.py # MCP server main entrypoint
│ ├── health_server.py # HTTP health endpoint
│ └── src/ # MCP tools and resources
├── modules/
│ └── ingest/ # Ingestion pipeline
│ ├── core/
│ │ ├── 🔄 pipeline.py # Multi-language ingestion orchestrator
│ │ ├── ⚙️ config.py # Repository and ingestion configuration
│ │ ├── 🔗 vector_backend.py # Vector backend abstraction (Qdrant)
│ │ ├── 🔗 embedding_service.py # Embedding generation (DeepInfra)
│ │ ├── 📦 batch_processor.py # Concurrent batch processing
│ │ ├── 💾 storage_manager.py # Vector storage management
│ │ ├── ✅ checkpoint_manager.py # Resume from interruption
│ │ ├── 📋 file_processor.py # File parsing coordination
│ │ └── 📊 metadata_schema.py # Vector metadata structure
│ ├── parsers/
│ │ ├── 🦀 rust_parser.py # Rust code AST parsing
│ │ ├── 📘 typescript_parser.py # TypeScript/JSX parsing
│ │ ├── ⚡ solidity_parser.py # Solidity contract parsing
│ │ ├── 📄 documentation_parser.py # Markdown documentation
│ │ ├── 🐍 yaml_parser.py # YAML configuration files
│ │ └── 🏗️ terraform_parser.py # Terraform infrastructure
│ ├── services/
│ │ ├── 🔗 vector_client.py # Qdrant database client
│ │ ├── 🔍 enhanced_ranking.py # Advanced search ranking
│ │ └── ✅ quality_validator.py # Code quality validation
│ ├── scripts/
│ │ ├── 🔄 repo_cloner.py # GitHub repository cloning
│ │ ├── 🗂️ collection_manager.py # Qdrant collection management
│ │ ├── 📊 stats_reporter.py # Statistics and reporting
│ │ ├── 📝 repo_metadata.py # Repository metadata capture
│ │ └── 🔍 search_test.py # Vector search testing
│ └── deploy/
│ └── 🚀 modal_deploy.py # Modal deployment orchestrator
│
└── repos/ # Cloned repositories (gitignored)
├── my-backend/ # Example: your backend service
├── my-frontend/ # Example: your frontend application
└── ... # Additional configured repositories🛠️ 可用命令
这些命令用于 本地Python 使用。使用Docker Compose，使用 docker compose up 并看到 用于服务控制。
🏗️ 设置和安装
make venv # Create virtual environment using uv
make install # Install Python dependencies
make sync # Sync dependencies with uv (faster)
make setup # Complete system setup (venv + install + check-env)
make check-env # Verify environment variables🗄️ 矢量数据库和摄入
make ingest # Full ingestion pipeline (all languages)
make ingest-warmup # Warm up embedding service before ingestion
make ingest-search QUERY='text' # Test vector search functionality
make vector-status # Check Qdrant collections and vector counts
make index-check # Check vector indexing progress📦 库管理
make clone-repos # Clone high-priority repos only (~10 repos)
make clone-repos-medium # Clone medium+high priority repos (~16 repos)
make clone-repos-all # Clone ALL configured repositories
make collection-cleanup # Clean/recreate all vector collections
make collection-status # Get detailed collection statistics
make repo-metadata # Capture repository commit metadata
make stats-report # Generate comprehensive statistics report⚙️ 系统管理
make health # System health check (ingestion + vector search)
make test # Run all tests
make clean # Clean up generated files and caches🏗️ 建筑
摄入管道流量
flowchart LR
A[GitHub Repos] --> B[Clone & Filter]
B --> C[Multi-Language Parsers]
C --> D[AST Extraction]
D --> E[Chunk Generation]
E --> F[Embedding Service]
F --> G[Vector DB]
G --> H[Semantic Search]组件
- 📂 存储库管理器 -使用基于优先级的选择克隆和管理GitHub存储库
- 🔍 语言分析器 -基于AST的Rust、TypeScript、Solidity和文档解析
- 🧠 嵌入服务 -通过DeepInfra实现最先进的嵌入（Qwen3-Embedded-8B，4096D）
- 💾 向量存储 -Qdrant提供特定语言的集合
- 🔎 搜索引擎 -具有增强排名的跨语言语义搜索
- 📊 监控 -健康检查、统计和质量验证
支持的语言和内容类型
- 🦀 锈 -完整的解析，包括宏、特征、异步代码和实现
- 📘 TypeScript -React组件、钩子、实用程序、类型定义和接口
- ⚡ Solidity -智能合约、接口、事件和部署脚本
- 📚 文档 -Markdown文件、知识库（黑曜石）、技术文档
- 🐍 YAML -配置文件、CI/CD管道、Kubernetes清单
- 🏗️ 地形 -基础设施即代码、资源定义、模块
🔧 配置
环境变量
Docker Compose （默认）：设置 DEEPINFRA_API_KEY 和 GITHUB_TOKEN 在 .env；Qdrant在堆栈中自动配置。
本地Python 或 Qdrant云:
# Qdrant configuration (optional - uses local Docker by default)
# For Qdrant Cloud:
QDRANT_URL=https://your-cluster.cloud.qdrant.io
QDRANT_API_KEY=your_qdrant_api_key
# For local Python (outside Docker):
QDRANT_URL=http://localhost:6333
# QDRANT_API_KEY not needed for local
# Embedding (required for both)
DEEPINFRA_API_KEY=your_deepinfra_key # https://deepinfra.com
# Repository cloning
GITHUB_TOKEN=your_github_pat_token集合配置
系统使用 config/collections.yaml 定义集合名称和前缀。摄取管道和MCP服务器都从该文件读取以确保一致性。
看 配置 有关存储库设置的详细信息，请参阅上文。
矢量数据库集合
- 代码集合:
rust,typescript,solidity（特定语言） - 文件收集:
documentation（知识库、技术文档） - 嵌入模型：Qwen3-Embedded-8B（4096维）
- 块大小：500个令牌，50个令牌重叠（代码），6k-12k个字符（文档）
- 分数阈值：0.3（余弦相似度）
🔍 矢量搜索功能
增强排名
- 语义相似度 使用余弦距离
- 文件类型相关性 提升
- 近期评分 用于最近修改的文件
- 特定语言的 收藏搜索
质量验证
- 语法验证 对于所有摄入的代码
- 内容过滤 删除注释和空文件
- 去重 通过块哈希防止冗余存储
- 错误处理 优美的后撤
搜索示例
# Search for authentication code
make ingest-search QUERY='authentication service'
# Search for specific patterns
make ingest-search QUERY='JWT token validation'
# Search across all languages
make ingest-search QUERY='database connection pool'📊 性能与监控
系统健康检查
make health # Pipeline status & connectivity
make vector-status # Detailed vector database metrics
make stats-report # Comprehensive ingestion statistics关键指标
- 矢量集合：所有集合中有50K以上的代码块
- 搜索延迟：语义查询\<200ms
- 嵌入生成：通过DeepInfra API（Qwen3-Embedding-8B型号）
- 摄入吞吐量：因回购规模和语言复杂性而异
- 文档块：智能节分组（每个块6k-12k个字符）
监控功能
- 实时摄取进度跟踪
- 集合级统计数据（点、索引向量、内存使用情况）
- 每个存储库的摄取指标
- 嵌入服务健康检查
- 基于检查点的恢复功能
🎯 用例
对于开发团队
- 代码搜索 -跨所有代码库的语义搜索
- 文档发现 -查找相关技术文档
- 跨存储库分析 -了解跨多个存储库的模式
- 知识库 -可搜索的组织知识
对于AI系统
- 上下文检索 -检索AI代理任务的相关代码
- 代码理解 -多语言语义代码理解
- 文档访问 -访问组织知识库
- 模式发现 -查找实现模式和示例
🛡️ 安全与最佳实践
代码质量指南
- 文件必须少于500行（严格执行）
- 所有类别的单一责任原则
- 全面的错误处理和验证
- 安全第一的方法，没有暴露的秘密
开发标准
- OOP第一设计 -专用类中的每个功能
- 模块化架构 -乐高式组件组成
- 检查点系统 -恢复长时间摄入的能力
- 批处理 -高效的并发嵌入生成
管道行为
收集策略
- 特定语言集合：每种语言都有自己的集合，以提高相关性
- 文件分离：文档单独存储，以防止代码模式污染
- 元数据丰富：每个块包括存储库、文件路径、语言和提交元数据
错误处理
- 故障弱化：失败的文件不会停止整个摄取过程
- 重试逻辑：临时嵌入服务失败时自动重试
- 检查点恢复：中断后从上次成功状态恢复
🤝 贡献
- 遵循中的指导方针
CLAUDE.md - 确保所有文件不超过500行
- 使用单一责任原则
- 为新功能添加全面的测试
- 维护安全最佳实践
📚 文档
docs/-完整的技术文档docs/modules/ingest/PIPELINE.md-摄入管道详细信息docs/modules/ingest/PARSERS.md-语言解析器文档CLAUDE.md-开发指南和编码标准Makefile-带示例的完整命令参考
🔗 相关技术
该工具包旨在支持多存储库代码搜索，可用于任何GitHub组织的存储库。
示例用例： 在中配置组织的存储库 config/repositories.yaml，运行摄取管道以矢量化您的代码库，并使用MCP服务器在IDE或AI工具中启用语义代码搜索。
关键技术：
- DeepInfra -嵌入服务API(https://deepinfra.com)
- Qdrant -用于语义搜索的矢量数据库
📄 许可证
MIT许可证-请参阅 LICENSE 文件以获取详细信息。
______________________________________________________________________
代码摄入系统 -将代码存储库转换为具有多语言支持和语义搜索的可搜索向量数据库。