Khoj GitHub 数据源集成PAT 配置、仓库索引流程与源码实现解析【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khojKhoj 内置的 GitHub 集成允许将任意数量的 Git 仓库作为个人知识源纳入索引让 Markdown、Org 和普通文本文件的片段可以被统一检索与问答。本文基于官方文档 github_integration.md 与仓库源码完整讲解该集成的配置步骤、配置数据模型、索引管线实现文件遍历、类型识别、限流处理、条目切分以及触发索引的服务端调用链帮助你在自建 Khoj 时正确接入 GitHub 仓库数据源并理解其底层工作机制。功能定位与当前维护状态在展开配置细节之前需要明确该集成的定位和现状核心能力可以索引任意数量的 GitHub 仓库。默认配置下每个仓库中的所有 Markdown.md、Org.org和文本Text文件都会被索引。性能特征对于大型仓库索引耗时相当长但用于较小的项目时工作良好。维护状态重要官方文档以醒目警告标明GitHub 集成目前处于未维护状态且官方正在考虑将其弃用原因是使用人数不多且维护成本高。因此将其作为生产级依赖时应知悉这一风险。配置步骤从 PAT 到开始检索完整的配置流程如下源自官方文档的 4 步操作生成 Personal Access Token在 GitHub 的 token 设置页生成一个classic PATclassic 类型的 Personal Access Token权限范围至少需要repo和admin:org两个 scope。填写 Khoj 设置登录 Khoj 的 Web 设置页官方文档指向https://app.khoj.dev/settings下的 GitHub 数据源区块填入 PAT并为每个要索引的仓库填写详细信息仓库名、仓库所属人/组织、分支。保存并触发索引点击Save保存 GitHub 设置返回设置页后点击Configure执行数据源配置服务端随即启动索引流程。开始使用回到 Khoj 主页即可开始检索已索引的仓库内容。从源码看仓库级配置的粒度是owner/name/branch三元组分支未显式指定时默认为master这一点在配置模型中有明确体现见下文。配置数据模型PAT 与仓库列表如何存储Khoj 将 GitHub 数据源配置持久化在数据库中对应两张表见 database modelsclass GithubConfig(DbBaseModel): pat_token models.CharField(max_length200) user models.ForeignKey(KhojUser, on_deletemodels.CASCADE) class GithubRepoConfig(DbBaseModel): name models.CharField(max_length200) owner models.CharField(max_length200) branch models.CharField(max_length200) github_config models.ForeignKey(GithubConfig, on_deletemodels.CASCADE, related_namegithubrepoconfig)GithubConfig按用户维度存储 PATpat_token一个用户一份。GithubRepoConfig与GithubConfig一对多每行代表一个待索引仓库字段为name仓库名、owner仓库所属人或组织、branch要索引的分支。在 API 层这两个模型会被组装成 Pydantic 配置对象GithubContentConfig见 rawconfigclass GithubRepoConfig(ConfigBase): name: str owner: str branch: Optional[str] master # 未指定分支时默认 master class GithubContentConfig(ConfigBase): pat_token: Optional[str] None repos: List[GithubRepoConfig]也就是说设置页提交的配置本质上是一个{pat_token, repos: [{name, owner, branch}]}结构的 JSON。相关配置接口由 api_content.py 提供GET /github读取当前用户配置并回显给前端用于设置页表单回填POST /github接收GithubContentConfig通过 数据库适配器 的set_user_github_config写入GithubConfig与关联的仓库记录并记录一条content_typegithub的遥测事件。索引管线GithubToEntries 的实现细节索引执行主体是 GithubToEntries 类它继承自TextToEntries。构造函数从数据库读取GithubConfig组装出GithubContentConfig并初始化一个带鉴权头的requests.Sessionself.session requests.Session() if not is_none_or_empty(self.config.pat_token): self.session.headers.update({Authorization: ftoken {self.config.pat_token}})1. 文件发现Git Trees API 递归遍历对每个仓库索引器通过仓库内容接口递归拉取整棵文件树get_filesrepo_content_url f{repo_url}/git/trees/{repo.branch} params {recursive: true} response requests.get(repo_content_url, headersheaders, paramsparams)请求的是https://api.github.com/repos/{owner}/{name}/git/trees/{branch}并附带recursivetrue参数一次拿到分支下全部文件条目。这正是官方文档所说“默认索引仓库里所有文件”的实现方式——它不做路径过滤而是遍历整棵树再按类型筛选。2. 三类文件的分类与筛选遍历tree时get_files文件按以下规则分流入三个列表文件类型判定条件处理方式Markdown路径以.md结尾的 blob直接下载内容路径记录为仓库 blob 的浏览器 URLOrg 模式路径以.org结尾的 blob同上其余 blob所有其他非二进制文件先下载原始字节用 Google 的Magika做内容类型识别仅当识别结果为text或code时才以 UTF-8 解码后纳入索引识别失败或解码失败的文件会被跳过并记录日志这个 Magika 兜底逻辑解释了“Text files”的准确含义并非某个固定扩展名集合而是任何被识别为文本/代码类内容的非 Markdown/Org 文件例如源码文件、纯文本笔记等二进制文件图片、编译产物等会被天然排除。每个被收录的文件都会记录一个指向仓库中对应文件 blob 页的 URLhttps://github.com/{owner}/{name}/blob/{branch}/{path}后续检索结果即可跳转回源文件。3. 内容下载与限流保护文件内容通过Accept: application/vnd.github.v3.raw请求头以原始流式方式逐块下载2048 字节/块见 get_file_contents。限流是 GitHub REST API 的核心约束源码中有多处对应处理单文件下载时若响应非 200 且X-RateLimit-Remaining为0直接抛出ConnectionAbortedError(Github rate limit reached)中止当前仓库索引并向上抛出仓库级process_repo 捕获该异常后记录“Github rate limit reached. Skip indexing github repo”通用等待逻辑wait_for_rate_limit_reset工具方法会根据X-RateLimit-Reset头计算剩余等待秒数time.sleep到限流窗口重置后自动重试wait_for_rate_limit_reset。另外若未配置 PAT索引流程会打印警告“Github PAT token is not set. Private repositories cannot be indexed and lower rate limits apply.”——即没有 PAT 时无法索引私有仓库且受更低的匿名速率限制约束这也是文档要求提供带reposcope 的 PAT 的根本原因。4. 条目提取、切分与入库三类文件分别交由各自的转换器提取条目current_entries MarkdownToEntries.convert_markdown_entries_to_maps( *GithubToEntries.extract_markdown_entries(markdown_files)) current_entries OrgToEntries.convert_org_nodes_to_entries( *GithubToEntries.extract_org_entries(org_files)) current_entries PlaintextToEntries.convert_text_files_to_entries( *GithubToEntries.extract_plaintext_entries(plaintext_files)) current_entries TextToEntries.split_entries_by_max_tokens(current_entries, max_tokens256)Markdown 文件按标题结构切块复用 markdown_to_entries 的process_single_markdown_fileOrg 文件复用 org_to_entries 的节点解析纯文本文件走 plaintext_to_entries 的通用切分最后统一按max_tokens256将超长条目切分以适配嵌入模型的 token 上限。条目落库时打上EntryType.GITHUB与EntrySource.GITHUB标记并以compiled字段做新旧比对增量更新见 update_entries_with_ids返回新增与删除的嵌入数量。索引何时被触发服务端调用链配置保存后索引并非立刻独立运行而是挂在 Khoj 的检索初始化流程中。在 routers/helpers.py 中可以看到触发条件# Run server side indexing of user Github docs if no client sent documents if no_client_sent_documents: github_config GithubConfig.objects.filter(useruser).prefetch_related(githubrepoconfig).first() if ( search_type state.SearchType.All.value or search_type state.SearchType.Github.value ) and github_config is not None: logger.info( Setting up search for github) # Extract Entries, Generate Github Embeddings text_search.setup( GithubToEntries, None, regenerateregenerate, useruser, configgithub_config, )从这段调用链可以确认三个关键前提客户端未携带文档no_client_sent_documents时才走服务端索引——即 Web 端场景桌面/Emacs 等客户端自行发送文件时不触发搜索类型为all或github之一用户存在 GitHub 配置GithubConfig记录非空。满足后text_search.setup会执行GithubToEntries的完整流程提取条目 → 生成嵌入 → 增量写入数据库。这与文档中“点击 Configure 后仓库内容即可被检索”的体验对应。使用建议与限制结合文档声明与源码行为实际使用 GitHub 集成时应注意优先选择小仓库文件发现阶段对整棵 git tree 做递归拉取且每个文件单独发起 raw 下载请求请求数量与仓库文件数成正比。仓库越大耗时越长、越容易触碰限流。务必配置 PAT除解锁私有仓库索引外认证请求的速率配额显著高于匿名请求是大型仓库能否完成索引的关键。限流即中断触发速率限制时当前仓库索引会被跳过ConnectionAbortedError而非静默截断可待限流窗口重置后重新 Configure。分支粒度每个仓库条目绑定单个branch默认master若仓库默认分支是main应在设置中显式指定否则会因找不到树而索引为空tree 请求失败或无tree字段时返回空列表。关注弃用风险官方已明确该集成处于未维护、考虑弃用的状态若需长期依赖建议以本地文件、Notion 等数据源作为主渠道GitHub 仓库索引仅作补充。小结Khoj 的 GitHub 集成将“仓库 → 文本条目 → 嵌入 → 统一检索”这条链路完整实现了出来GithubConfig/GithubRepoConfig表承载owner/name/branch粒度的配置GithubToEntries通过 Git Trees API 递归遍历、Magika 类型识别、限流感知的流式下载将.md/.org及一切被识别为文本/代码的文件按 256 token 上限切块入库。理解上述实现细节后你可以准确预判该集成在不同规模仓库上的行为与瓶颈并在官方弃用该功能前做出合理的技术取舍。【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khoj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Khoj GitHub 数据源集成：PAT 配置、仓库索引流程与源码实现解析
Khoj GitHub 数据源集成PAT 配置、仓库索引流程与源码实现解析【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khojKhoj 内置的 GitHub 集成允许将任意数量的 Git 仓库作为个人知识源纳入索引让 Markdown、Org 和普通文本文件的片段可以被统一检索与问答。本文基于官方文档 github_integration.md 与仓库源码完整讲解该集成的配置步骤、配置数据模型、索引管线实现文件遍历、类型识别、限流处理、条目切分以及触发索引的服务端调用链帮助你在自建 Khoj 时正确接入 GitHub 仓库数据源并理解其底层工作机制。功能定位与当前维护状态在展开配置细节之前需要明确该集成的定位和现状核心能力可以索引任意数量的 GitHub 仓库。默认配置下每个仓库中的所有 Markdown.md、Org.org和文本Text文件都会被索引。性能特征对于大型仓库索引耗时相当长但用于较小的项目时工作良好。维护状态重要官方文档以醒目警告标明GitHub 集成目前处于未维护状态且官方正在考虑将其弃用原因是使用人数不多且维护成本高。因此将其作为生产级依赖时应知悉这一风险。配置步骤从 PAT 到开始检索完整的配置流程如下源自官方文档的 4 步操作生成 Personal Access Token在 GitHub 的 token 设置页生成一个classic PATclassic 类型的 Personal Access Token权限范围至少需要repo和admin:org两个 scope。填写 Khoj 设置登录 Khoj 的 Web 设置页官方文档指向https://app.khoj.dev/settings下的 GitHub 数据源区块填入 PAT并为每个要索引的仓库填写详细信息仓库名、仓库所属人/组织、分支。保存并触发索引点击Save保存 GitHub 设置返回设置页后点击Configure执行数据源配置服务端随即启动索引流程。开始使用回到 Khoj 主页即可开始检索已索引的仓库内容。从源码看仓库级配置的粒度是owner/name/branch三元组分支未显式指定时默认为master这一点在配置模型中有明确体现见下文。配置数据模型PAT 与仓库列表如何存储Khoj 将 GitHub 数据源配置持久化在数据库中对应两张表见 database modelsclass GithubConfig(DbBaseModel): pat_token models.CharField(max_length200) user models.ForeignKey(KhojUser, on_deletemodels.CASCADE) class GithubRepoConfig(DbBaseModel): name models.CharField(max_length200) owner models.CharField(max_length200) branch models.CharField(max_length200) github_config models.ForeignKey(GithubConfig, on_deletemodels.CASCADE, related_namegithubrepoconfig)GithubConfig按用户维度存储 PATpat_token一个用户一份。GithubRepoConfig与GithubConfig一对多每行代表一个待索引仓库字段为name仓库名、owner仓库所属人或组织、branch要索引的分支。在 API 层这两个模型会被组装成 Pydantic 配置对象GithubContentConfig见 rawconfigclass GithubRepoConfig(ConfigBase): name: str owner: str branch: Optional[str] master # 未指定分支时默认 master class GithubContentConfig(ConfigBase): pat_token: Optional[str] None repos: List[GithubRepoConfig]也就是说设置页提交的配置本质上是一个{pat_token, repos: [{name, owner, branch}]}结构的 JSON。相关配置接口由 api_content.py 提供GET /github读取当前用户配置并回显给前端用于设置页表单回填POST /github接收GithubContentConfig通过 数据库适配器 的set_user_github_config写入GithubConfig与关联的仓库记录并记录一条content_typegithub的遥测事件。索引管线GithubToEntries 的实现细节索引执行主体是 GithubToEntries 类它继承自TextToEntries。构造函数从数据库读取GithubConfig组装出GithubContentConfig并初始化一个带鉴权头的requests.Sessionself.session requests.Session() if not is_none_or_empty(self.config.pat_token): self.session.headers.update({Authorization: ftoken {self.config.pat_token}})1. 文件发现Git Trees API 递归遍历对每个仓库索引器通过仓库内容接口递归拉取整棵文件树get_filesrepo_content_url f{repo_url}/git/trees/{repo.branch} params {recursive: true} response requests.get(repo_content_url, headersheaders, paramsparams)请求的是https://api.github.com/repos/{owner}/{name}/git/trees/{branch}并附带recursivetrue参数一次拿到分支下全部文件条目。这正是官方文档所说“默认索引仓库里所有文件”的实现方式——它不做路径过滤而是遍历整棵树再按类型筛选。2. 三类文件的分类与筛选遍历tree时get_files文件按以下规则分流入三个列表文件类型判定条件处理方式Markdown路径以.md结尾的 blob直接下载内容路径记录为仓库 blob 的浏览器 URLOrg 模式路径以.org结尾的 blob同上其余 blob所有其他非二进制文件先下载原始字节用 Google 的Magika做内容类型识别仅当识别结果为text或code时才以 UTF-8 解码后纳入索引识别失败或解码失败的文件会被跳过并记录日志这个 Magika 兜底逻辑解释了“Text files”的准确含义并非某个固定扩展名集合而是任何被识别为文本/代码类内容的非 Markdown/Org 文件例如源码文件、纯文本笔记等二进制文件图片、编译产物等会被天然排除。每个被收录的文件都会记录一个指向仓库中对应文件 blob 页的 URLhttps://github.com/{owner}/{name}/blob/{branch}/{path}后续检索结果即可跳转回源文件。3. 内容下载与限流保护文件内容通过Accept: application/vnd.github.v3.raw请求头以原始流式方式逐块下载2048 字节/块见 get_file_contents。限流是 GitHub REST API 的核心约束源码中有多处对应处理单文件下载时若响应非 200 且X-RateLimit-Remaining为0直接抛出ConnectionAbortedError(Github rate limit reached)中止当前仓库索引并向上抛出仓库级process_repo 捕获该异常后记录“Github rate limit reached. Skip indexing github repo”通用等待逻辑wait_for_rate_limit_reset工具方法会根据X-RateLimit-Reset头计算剩余等待秒数time.sleep到限流窗口重置后自动重试wait_for_rate_limit_reset。另外若未配置 PAT索引流程会打印警告“Github PAT token is not set. Private repositories cannot be indexed and lower rate limits apply.”——即没有 PAT 时无法索引私有仓库且受更低的匿名速率限制约束这也是文档要求提供带reposcope 的 PAT 的根本原因。4. 条目提取、切分与入库三类文件分别交由各自的转换器提取条目current_entries MarkdownToEntries.convert_markdown_entries_to_maps( *GithubToEntries.extract_markdown_entries(markdown_files)) current_entries OrgToEntries.convert_org_nodes_to_entries( *GithubToEntries.extract_org_entries(org_files)) current_entries PlaintextToEntries.convert_text_files_to_entries( *GithubToEntries.extract_plaintext_entries(plaintext_files)) current_entries TextToEntries.split_entries_by_max_tokens(current_entries, max_tokens256)Markdown 文件按标题结构切块复用 markdown_to_entries 的process_single_markdown_fileOrg 文件复用 org_to_entries 的节点解析纯文本文件走 plaintext_to_entries 的通用切分最后统一按max_tokens256将超长条目切分以适配嵌入模型的 token 上限。条目落库时打上EntryType.GITHUB与EntrySource.GITHUB标记并以compiled字段做新旧比对增量更新见 update_entries_with_ids返回新增与删除的嵌入数量。索引何时被触发服务端调用链配置保存后索引并非立刻独立运行而是挂在 Khoj 的检索初始化流程中。在 routers/helpers.py 中可以看到触发条件# Run server side indexing of user Github docs if no client sent documents if no_client_sent_documents: github_config GithubConfig.objects.filter(useruser).prefetch_related(githubrepoconfig).first() if ( search_type state.SearchType.All.value or search_type state.SearchType.Github.value ) and github_config is not None: logger.info( Setting up search for github) # Extract Entries, Generate Github Embeddings text_search.setup( GithubToEntries, None, regenerateregenerate, useruser, configgithub_config, )从这段调用链可以确认三个关键前提客户端未携带文档no_client_sent_documents时才走服务端索引——即 Web 端场景桌面/Emacs 等客户端自行发送文件时不触发搜索类型为all或github之一用户存在 GitHub 配置GithubConfig记录非空。满足后text_search.setup会执行GithubToEntries的完整流程提取条目 → 生成嵌入 → 增量写入数据库。这与文档中“点击 Configure 后仓库内容即可被检索”的体验对应。使用建议与限制结合文档声明与源码行为实际使用 GitHub 集成时应注意优先选择小仓库文件发现阶段对整棵 git tree 做递归拉取且每个文件单独发起 raw 下载请求请求数量与仓库文件数成正比。仓库越大耗时越长、越容易触碰限流。务必配置 PAT除解锁私有仓库索引外认证请求的速率配额显著高于匿名请求是大型仓库能否完成索引的关键。限流即中断触发速率限制时当前仓库索引会被跳过ConnectionAbortedError而非静默截断可待限流窗口重置后重新 Configure。分支粒度每个仓库条目绑定单个branch默认master若仓库默认分支是main应在设置中显式指定否则会因找不到树而索引为空tree 请求失败或无tree字段时返回空列表。关注弃用风险官方已明确该集成处于未维护、考虑弃用的状态若需长期依赖建议以本地文件、Notion 等数据源作为主渠道GitHub 仓库索引仅作补充。小结Khoj 的 GitHub 集成将“仓库 → 文本条目 → 嵌入 → 统一检索”这条链路完整实现了出来GithubConfig/GithubRepoConfig表承载owner/name/branch粒度的配置GithubToEntries通过 Git Trees API 递归遍历、Magika 类型识别、限流感知的流式下载将.md/.org及一切被识别为文本/代码的文件按 256 token 上限切块入库。理解上述实现细节后你可以准确预判该集成在不同规模仓库上的行为与瓶颈并在官方弃用该功能前做出合理的技术取舍。【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khoj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考