# https://github.com/postgresml/korvus 项目说明书
生成时间：2026-07-02 12:25:11 UTC
## 目录
- [Korvus 概览与快速入门](#page-1)
- [多语言 SDK 绑定与 API 参考](#page-2)
- [核心管道架构与数据流](#page-3)
- [部署、CLI、扩展与故障排查](#page-4)
## Korvus 概览与快速入门
### 相关页面
相关主题：[多语言 SDK 绑定与 API 参考](#page-2), [核心管道架构与数据流](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/postgresml/korvus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md)
- [korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)
- [korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
- [korvus/src/pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)
- [korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
- [korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
- [korvus/javascript/package.json](https://github.com/postgresml/korvus/blob/main/korvus/javascript/package.json)
- [rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)
- [rust-bridge/rust-bridge-macros/src/lib.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/lib.rs)
# Korvus 概览与快速入门
## 1. 项目定位与核心价值
Korvus 是一个面向 Postgres 的全开源、端到端 RAG（Retrieval-Augmented Generation）流水线框架。它将大语言模型、向量存储、嵌入生成、重排序、摘要以及自定义模型统一到单条 SQL 查询中，旨在替代 OpenAI + Pinecone 的组合方案。Korvus 基于 Postgres 构建，并通过 PgVector 实现高效的向量检索，使开发者无需维护额外的专用向量数据库基础设施。
资料来源：[README.md](https://github.com/postgresml/korvus/blob/main/README.md)
根据 [`korvus/src/lib.rs`](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs) 中的模块声明，SDK 内置了对文档表、文本分块、文本分割器、LLM 模型与嵌入向量的统一管理能力，并借助 `sqlx`、`PgPool` 等异步运行时组件与 Postgres 建立连接。核心 Rust crate 通过 `tokio` 异步执行器驱动所有数据库与模型调用。
资料来源：[korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)
## 2. 系统架构
Korvus 的核心架构采用 Rust 作为底层实现，通过自研的 `rust-bridge` 过程宏自动生成 Python（PyO3）与 JavaScript（Neon）绑定，从而在保持单一代码源的前提下提供多语言 SDK。
```mermaid
flowchart LR
A[用户应用
Python / JS / Rust] --> B[Korvus SDK]
B --> C[Collection
文档与流水线管理]
C --> D[Pipeline
转换与处理链]
D --> E[Model
嵌入与 LLM]
D --> F[Splitter
文本分块]
E --> G[(Postgres + PgVector)]
F --> G
G --> H[向量检索 / RAG 结果]
H --> A
```
核心数据结构 `Collection` 与 `Pipeline` 均通过 `#[cfg_attr(feature = "rust_bridge", derive(alias))]` 派生宏标识，使其可被自动翻译为多语言绑定。`Pipeline` 通过 JSON Schema 描述字段级别的转换动作，由 `json_to_schema` 解析为内部 `ParsedSchema`。
资料来源：[korvus/src/pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs) ; [korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
## 3. 支持的任务类型与语言绑定
Korvus 通过 [`ProjectTask`](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs) 枚举覆盖了主流的机器学习与 NLP 任务，其与字符串标识的映射关系如下表所示：
| 枚举变体 | 字符串标识 | 典型用途 |
|---|---|---|
| Regression | `regression` | 数值回归 |
| Classification | `classification` | 多类别分类 |
| QuestionAnswering | `question_answering` | 抽取式问答 |
| Summarization | `summarization` | 文本摘要 |
| Translation | `translation` | 机器翻译 |
| TextClassification | `text_classification` | 文本分类 |
| TextGeneration | `text_generation` | 文本生成 |
| Text2text | `text2text` | 序列到序列 |
| Embedding | `embedding` | 嵌入向量生成 |
资料来源：[korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
在语言层面，`korvus/src/lib.rs` 通过 Cargo features 控制模块可见性，已官方支持 Python（`feature = "python"`）、JavaScript（`feature = "javascript"`）与 C（`feature = "c"`）。`rust-bridge` 子 crate 中的 `alias` 与 `alias_methods` 过程宏会读取同一份 Rust 源码并生成对应的 FFI 绑定，实现"一次实现，多端发布"。
资料来源：[korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs) ; [rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md) ; [rust-bridge/rust-bridge-macros/src/lib.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/lib.rs)
## 4. 快速入门
### 4.1 环境准备
Korvus 依赖 Postgres + PgVector。在配置好 `DATABASE_URL`（或 JavaScript 端的 `KORVUS_DATABASE_URL`）后，可使用 pip 或 npm 安装对应语言的 SDK。当前 JavaScript 包的版本号为 `1.1.5`，由 `cargo-cp-artifact` 自动产出原生绑定。
资料来源：[korvus/javascript/package.json](https://github.com/postgresml/korvus/blob/main/korvus/javascript/package.json)
### 4.2 Python 示例
Python 示例位于 [`korvus/python/examples`](https://github.com/postgresml/korvus/tree/main/korvus/python/examples)，主要涵盖以下场景：
- `semantic_search.py`：基于 Quora 数据集构建集合，使用 `intfloat/e5-small-v2` 模型生成嵌入并执行向量检索。
- `question_answering.py`：基于 SQuAD 数据集演示检索增强问答。
- `question_answering_instructor.py`：演示使用 `hknlp/instructor-base` 等自定义嵌入模型。
- `extractive_question_answering.py`：通过 `Builtins.transform()` 在数据库内执行 HuggingFace 问答模型。
环境变量设置：`export KORVUS_DATABASE_URL={YOUR DATABASE URL}`，也可写入 `.env` 文件。
资料来源：[korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
### 4.3 JavaScript 示例
JavaScript 示例位于 [`korvus/javascript/examples`](https://github.com/postgresml/korvus/tree/main/korvus/javascript/examples)，与 Python 端基本一一对应，包括语义检索、问答、Instructor 模型与摘要问答，并额外提供 Webpack 集成示例。安装依赖后设置 `KORVUS_DATABASE_URL` 即可运行。
资料来源：[korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
### 4.4 自定义 HuggingFace 模型
社区 Issue #13 中指出：在 Pipeline 中使用 HuggingFace 模型时，需要在模型配置中显式传入 `trust_remote_code=True`，否则无法加载远程自定义代码。这是一项常见的环境配置踩点，开发者应在初始化 Pipeline 时核对模型参数。
资料来源：[GitHub Issue #13](https://github.com/postgresml/korvus/issues/13)
## 5. 社区关注与已知问题
- **多语言绑定诉求**：社区已提出添加 Go（Issue #6）、PHP（Issue #9）、.NET（Issue #24）等语言绑定的请求。受限于当前 `rust-bridge` 仅内置 Python / JavaScript / C 的代码生成器，这些语言暂未纳入官方支持路线。
- **文档缺口**：Issue #13 反映了示例脚本运行步骤的文档缺失，例如 HuggingFace 模型参数 `trust_remote_code` 的传递方式。
- **云端运行稳定性**：Issue #23 报告 Korvus Cloud 上的流水线出现 `os error 11`（资源耗尽类错误），需重启 worker 恢复。该问题多见于模型推理阶段的资源争用场景。
资料来源：[GitHub Issues #6, #9, #13, #23, #24](https://github.com/postgresml/korvus/issues)
## 6. 贡献与支持
项目欢迎通过 Fork + Pull Request 的方式贡献代码，提交前请阅读 [`CONTRIBUTING.md`](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md) 中的编码规范与测试要求。日常问题可通过 Discord 与 Twitter 社区进行交流，企业级支持请联系 PostgresML 官方。
资料来源：[CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md) ; [README.md](https://github.com/postgresml/korvus/blob/main/README.md)
## See Also
- [Korvus 集合（Collection）与流水线（Pipeline）模型](Korvus-Collection-and-Pipeline-Models)
- [rust-bridge 多语言绑定机制](rust-bridge-Multi-Language-Bindings)
- [PostgresML 官方文档](https://postgresml.org/docs/open-source/korvus/)
---
## 多语言 SDK 绑定与 API 参考
### 相关页面
相关主题：[Korvus 概览与快速入门](#page-1), [核心管道架构与数据流](#page-3), [部署、CLI、扩展与故障排查](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)
- [korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
- [korvus/src/pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)
- [korvus/src/models.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/models.rs)
- [korvus/src/languages/mod.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/languages/mod.rs)
- [rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)
- [rust-bridge/rust-bridge-macros/src/lib.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/lib.rs)
- [rust-bridge/rust-bridge-macros/src/python.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/python.rs)
- [rust-bridge/rust-bridge-macros/src/c.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/c.rs)
- [rust-bridge/rust-bridge-macros/src/common.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/common.rs)
- [rust-bridge/rust-bridge-macros/src/types.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/types.rs)
- [README.md](https://github.com/postgresml/korvus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md)
- [korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
- [korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
# 多语言 SDK 绑定与 API 参考
## 概览
Korvus 是一个基于 Rust 构建的端到端向量搜索 SDK，允许用户在不使用 OpenAI 与 Pinecone 的前提下，借助 PostgresML 与 PgVector 完成文档摄取、文本分块、向量化与检索任务 [README.md:1-10]。项目的核心 Rust 库位于 [`korvus/src/lib.rs`](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)，并通过 `Builtins`、`Collection`、`Model`、`Pipeline`、`Splitter`、`TransformerPipeline` 等公开类型对外暴露能力 [korvus/src/lib.rs:25-35]。
为了让 Python、JavaScript 与 C 用户都能使用同一套核心逻辑，Korvus 设计了一套基于过程宏的 Rust-to-Rust 转换框架 [`rust-bridge`](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)，从而以单一代码源同时生成 PyO3 与 Neon 兼容的绑定代码。
## 绑定生成架构
```mermaid
flowchart LR
A[核心 Rust 类型
Collection / Pipeline / Model] --> B[rust-bridge 过程宏
alias / alias_methods]
B --> C{目标语言}
C -->|Python| D[PyO3 绑定
generate_python_*]
C -->|JavaScript| E[Neon 绑定
generate_javascript_*]
C -->|C| F[C FFI 绑定
generate_c_*]
D --> G[korvus-python]
E --> H[korvus-javascript]
F --> I[korvus-c]
```
`rust-bridge-macros` 是整个多语言绑定体系的中枢，它提供三个核心派生宏：`alias`、`alias_methods` 与 `alias_manual` [rust-bridge/rust-bridge-macros/src/lib.rs:11-44]。其中：
- `alias` 在编译期为 Rust 结构体生成 `Python`、`Javascript`、`C` 等包装结构，并实现跨语言互转 [rust-bridge/rust-bridge-macros/src/c.rs:9-44]。
- `alias_methods` 遍历 `impl` 块，按 `SupportedLanguage` 枚举（C / Python / JavaScript）为每个目标语言生成对应的方法签名，可通过 `skip = "..."` 跳过指定语言 [rust-bridge/rust-bridge-macros/src/common.rs:14-30]。
- 类型系统位于 [`types.rs`](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/types.rs)，负责将 Rust 类型映射为各语言可识别的字符串表达，例如 `Option` 会被映射为 `Option`、`Vec` 映射为 `Vec` [rust-bridge/rust-bridge-macros/src/types.rs]。
Korvus 在入口模块按特性门控加载对应语言绑定：[`korvus/src/languages/mod.rs`](https://github.com/postgresml/korvus/blob/main/korvus/src/languages/mod.rs) 通过 `#[cfg(feature = "javascript")]`、`#[cfg(feature = "python")]`、`#[cfg(feature = "c")]` 三个条件编译块启用不同模块。
## 已支持的语言绑定
| 语言 | 绑定机制 | 包入口 | 关键示例 |
|------|----------|--------|----------|
| Python | PyO3 + maturin | `korvus/python/korvus/` | `semantic_search.py`、`rag_question_answering.py` [korvus/python/examples/README.md] |
| JavaScript | Neon + napi-rs | `korvus/javascript/index.js` | `semantic_search.js`、`extractive_question_answering.js` [korvus/javascript/examples/README.md] |
| C | 裸 FFI + `Box::into_raw` | 由 `alias_methods` 自动生成 `*mut C` 句柄 | 见 `generate_c_alias` [rust-bridge/rust-bridge-macros/src/c.rs:9-80] |
以 `Collection` 为例：核心 Rust 结构体仅需声明一次，配合 `#[cfg_attr(feature = "rust_bridge", derive(alias))]` 即可在编译时为三种语言生成包装类型 [`korvus/src/collection.rs:55-65`](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)。其方法则通过 `#[cfg_attr(feature = "rust_bridge", alias_methods(new, upsert_documents, get_documents, ...))]` 显式登记到跨语言接口列表中 [korvus/src/collection.rs:65-79]。
Python 侧的实现位于 [`rust-bridge-macros/src/python.rs`](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/python.rs)：宏会判断方法是否为 `async`，并按 `OutputType::Result | OutputType::Other` 分别生成 `PyResult` 包装，从而保证 Rust 的 `anyhow::Result` 与 Python 异常体系正确桥接 [rust-bridge/rust-bridge-macros/src/python.rs]。
## 核心 API 参考
### Collection
`Collection` 表示一组文档及其关联的 Pipelines。其 Rust 结构同时保存 `name`、`database_url`、`pipelines_table_name`、`documents_table_name` 与可选的数据库元数据 [`korvus/src/collection.rs:55-65`](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)。暴露给跨语言的方法包括：
| 方法 | 用途 |
|------|------|
| `new` | 构造一个新的 Collection 实例 |
| `upsert_documents` / `get_documents` / `delete_documents` | 文档 CRUD |
| `add_pipeline` / `remove_pipeline` / `get_pipeline` / `get_pipelines` | Pipeline 管理 |
| `enable_pipeline` / `disable_pipeline` | Pipeline 状态切换 |
| `search` / `vector_search` | 混合 / 纯向量检索 |
### Pipeline
`Pipeline` 描述对每个字段执行的转换序列，由 JSON schema 驱动。`Pipeline::new` 接收 `name` 与 `schema` 两个参数，并通过 `json_to_schema` 校验 schema 中无重复键 [`korvus/src/pipeline.rs:24-46`](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)。Pipeline 支持的字段动作由 `ValidFieldAction` 反序列化，并在构造期通过 `try_into` 提前实例化模型与分块器 [`korvus/src/pipeline.rs:32-44`](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)。
### ProjectTask
`ProjectTask` 枚举定义了 SDK 已知的所有任务类型：`Regression`、`Classification`、`QuestionAnswering`、`Summarization`、`Translation`、`TextClassification`、`TextGeneration`、`Text2text`、`Embedding` [`korvus/src/collection.rs:5-25`](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)。它通过 `From<&str>` 与 `From<&ProjectTask> for &'static str` 双向转换，便于与 Postgres 字符串字段交互 [`korvus/src/collection.rs:27-65`](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)。
### Models 与 Builtins
数据模型 `Document`、`Collection`、`Embedding`、`Chunk`、`TSVector` 在 [`korvus/src/models.rs`](https://github.com/postgresml/korvus/blob/main/korvus/src/models.rs) 中通过 `sqlx::FromRow` 与 `enum_def` 派生，使其能直接在 SQL 查询结果上构造。`Builtins` 由 [`korvus/src/lib.rs:36`](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs) 重新导出，提供 `transform()` 等可在数据库端直接运行的 HuggingFace 模型调用能力（参见 [issue #13](https://github.com/postgresml/korvus/issues/13) 关于 `trust_remote_code: True` 的提醒）。
## 社区需求与未来扩展
根据仓库 Issue 跟踪，社区对更多语言绑定的呼声较高：
- **Golang**：见 [#6 Add Golang](https://github.com/postgresml/korvus/issues/6)。
- **PHP**：见 [#9 Add PHP](https://github.com/postgresml/korvus/issues/9)，主要用于 Laravel 生态。
- **.NET**：见 [#24 Add .net support](https://github.com/postgresml/korvus/issues/24)。
由于 [`rust-bridge-macros`](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/common.rs) 已通过 `SupportedLanguage` 枚举抽象出语言扩展点，新增一种语言只需实现对应的 `generate__alias` 与 `generate__methods` 函数，并在 [`korvus/src/languages/mod.rs`](https://github.com/postgresml/korvus/blob/main/korvus/src/languages/mod.rs) 中以 `#[cfg(feature = "...")]` 注册即可。贡献流程参见 [CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md)。
此外，#23 报告了 Korvus Cloud 上的 worker `os error 11` 问题，提示在托管环境中调用 `Builtins.transform()` 等需要远端模型推理的方法时，应关注宿主机资源与模型缓存状态。
## 参见
- 项目主页与安装说明：[README.md](https://github.com/postgresml/korvus/blob/main/README.md)
- Rust 桥接宏设计文档：[rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)
- Python 示例集合：[korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
- JavaScript 示例集合：[korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
- 官方文档：
---
## 核心管道架构与数据流
### 相关页面
相关主题：[多语言 SDK 绑定与 API 参考](#page-2), [部署、CLI、扩展与故障排查](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)
- [korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
- [korvus/src/pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)
- [korvus/src/transformer_pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/transformer_pipeline.rs)
- [korvus/src/model.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/model.rs)
- [korvus/src/builtins.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/builtins.rs)
- [korvus/src/languages/mod.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/languages/mod.rs)
- [rust-bridge/rust-bridge-macros/src/lib.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/lib.rs)
# 核心管道架构与数据流
## 1. 设计目标与定位
Korvus 是一个面向端到端向量搜索应用的开源 SDK 替代方案，目标是让用户在不使用 OpenAI / Pinecone 的前提下，统一管理文档、分块、向量嵌入、检索与生成任务。其核心抽象围绕「Collection（文档集合） + Pipeline（管道） + Model（模型） + Splitter（分块器）」四个对象展开，所有数据流均落到 PostgreSQL（通过 PgVector 扩展）中，避免引入额外的专用向量数据库。
资料来源：[korvus/src/lib.rs:1-15]()
> 社区关注点：Issue #13 多次反馈文档与示例脚本配置参数缺失（例如使用 Hugging Face 模型时需要 `trust_remote_code: true`），表明管道的配置语义是用户高频踩坑点；Issue #23 报告 Korvus Cloud worker 出现 `os error 11`，提示 Pipeline 在远端执行模型时存在资源隔离与崩溃恢复问题。
---
## 2. 核心组件
### 2.1 Collection — 文档与管道的容器
`Collection` 是用户操作的顶层对象，持有 `name`、`pipelines_table_name`、`documents_table_name` 等元数据，并保存 `CollectionDatabaseData`（含 `id`、`created_at`、`ProjectInfo`）等持久化信息。ProjectInfo 中包含 `task` 字段，枚举值涵盖 Regression、Classification、QuestionAnswering、Summarization、Translation、TextClassification、TextGeneration、Text2text 与 Embedding。
资料来源：[korvus/src/collection.rs:30-90]()
`Collection` 暴露的关键方法（通过 `alias_methods` 宏桥接至各语言）包括：`new`、`upsert_documents`、`get_documents`、`delete_documents`、`add_pipeline`、`remove_pipeline`、`enable_pipeline`、`disable_pipeline`、`search`、`vector_search` 等。这意味着同一份 Rust 源码可以同时给 Python、JavaScript、C 三套语言使用。
### 2.2 Pipeline 与 TransformerPipeline — 处理流水线
`Pipeline` 用于声明一条针对集合的处理/检索流程；`TransformerPipeline` 则是把 HuggingFace Transformer 模型在数据库侧执行的专用管道，配合 `Builtins.transform()` 完成抽取式问答、摘要问答等任务。用户可以在同一 Collection 上 `add_pipeline`、`enable_pipeline`、`disable_pipeline`，运行时只启用其中一条。
资料来源：[korvus/src/lib.rs:32-50]()；[korvus/src/transformer_pipeline.rs]()
### 2.3 Model 与 Splitter
`Model` 与 `Splitter` 作为独立模块被 `Collection` 通过特征方法组合调用：Splitter 负责把长文档切成 chunk，Model 负责把 chunk 编码为向量嵌入。二者均通过 `ProjectInfo.task` 决定行为（典型为 `Embedding`）。
资料来源：[korvus/src/model.rs]()；[korvus/src/lib.rs:30-42]()
### 2.4 Builtins — 数据库内转换
`Builtins` 是 `korvus` 重新导出的顶层工具集，包含 `transform()` 等内置方法，可在 PostgreSQL 内部直接调度 Transformer 模型，避免在应用层与数据库层之间来回搬运大块文本。
资料来源：[korvus/src/lib.rs:42-50]()
---
## 3. 端到端数据流
下图展示从原始文档写入到向量检索返回的完整管道数据流。
```mermaid
flowchart LR
A[原始文档 JSON] --> B[Collection.upsert_documents]
B --> C[PostgreSQL documents table]
C --> D[Splitter 切分 chunk]
D --> E[Model 编码为 Embedding]
E --> F[PgVector 存储]
F --> G[Collection.vector_search]
G --> H{是否需要生成?}
H -- 否 --> I[返回 Top-K 文档]
H -- 是 --> J[TransformerPipeline / Builtins.transform]
J --> K[问答 / 摘要结果]
```
关键点：
- 写入阶段：`Collection.upsert_documents` 把 JSON 文档落入 `documents_table_name` 指定表中。
- 索引阶段：Pipeline 在 Collection 上激活后，由 Splitter 生成 chunk，再由 Model 生成嵌入并写入向量列。
- 查询阶段：`Collection.vector_search` 接收 JSON 描述的 query（如 `{"query": {"fields": {"body": {"query": "...", "parameters": {"prompt": "query: "}}}}, "limit": 5}`），按相似度返回 Top-K。
- 生成阶段：若启用 TransformerPipeline，则 `Builtins.transform()` 在数据库内执行问答或摘要模型（例如 HuggingFace 的 QA 模型），并将检索结果作为 `context`。
资料来源：[korvus/src/lib.rs:test 示例片段]()；[korvus/javascript/examples/README.md:1-30]()
---
## 4. 多语言绑定机制
Korvus 的 SDK 在 Rust 核心之上，通过自定义过程宏 `alias` 与 `alias_methods` 自动派生 Python、JavaScript、C 三套 FFI 绑定。`rust-bridge` crate 会在同一份 Rust 源码上展开 `#[cfg(feature = "python")]`、`#[cfg(feature = "javascript")]`、`#[cfg(feature = "c")]` 三套实现。
资料来源：[rust-bridge/rust-bridge-macros/src/lib.rs:1-30]()；[korvus/src/languages/mod.rs]()
各语言的特性门控与入口：
| 语言 | 特性 flag | 绑定实现位置 |
| --- | --- | --- |
| Python | `python` | `korvus/src/languages/python` |
| JavaScript | `javascript` | `korvus/src/languages/javascript` |
| C | `c` | `korvus/src/languages/c` |
用户若希望新增语言（例如社区 Issue #6 提议的 Go、#9 提议的 PHP、#24 提议的 .NET），需要在 `rust-bridge` 中新增对应语言子模块，并在 `rust-bridge-traits` 中实现 traits，然后给 `Collection`/`Pipeline` 等结构体加上对应的 `alias_methods` 列表。
资料来源：[rust-bridge/rust-bridge-traits/src/lib.rs:1-5]()；[korvus/src/collection.rs:65-90]()
---
## 5. 常见失败模式与排障建议
根据社区 Issue 归纳：
- **Hugging Face 模型加载失败**：示例脚本缺少 `trust_remote_code: true`，需在 Pipeline 的 `parameters` 中显式传入。资料来源：Issue #13。
- **Cloud worker 崩溃（os error 11）**：通常与 Transformer 模型内存占用或模型下载中断相关，需在 Korvus Cloud 控制台重启 worker，或清理未完成的模型缓存。资料来源：Issue #23。
- **任务枚举越界**：`ProjectTask::from(&str)` 对未知字符串会 `panic!`，调用方应在自定义 Pipeline 配置前校验 task 名称。资料来源：[korvus/src/collection.rs:80-100]()。
- **跨语言方法未导出**：若新增方法未加入 `alias_methods(...)` 列表，Python/JS 端将看不到该方法。资料来源：[rust-bridge/rust-bridge-macros/src/lib.rs:30-50]()。
---
## See Also
- 集合与文档管理 API（Collection 模块详解）
- 向量检索 QueryBuilder 与 SearchQueryBuilder
- 多语言 SDK 绑定与 rust-bridge 宏
- Korvus Cloud 部署与 worker 排障指南
---
## 部署、CLI、扩展与故障排查
### 相关页面
相关主题：[多语言 SDK 绑定与 API 参考](#page-2), [核心管道架构与数据流](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [korvus/src/lib.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/lib.rs)
- [korvus/src/collection.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/collection.rs)
- [korvus/src/languages/mod.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/languages/mod.rs)
- [rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)
- [rust-bridge/rust-bridge-macros/src/lib.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/lib.rs)
- [rust-bridge/rust-bridge-macros/src/python.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/python.rs)
- [rust-bridge/rust-bridge-macros/src/types.rs](https://github.com/postgresml/korvus/blob/main/rust-bridge/rust-bridge-macros/src/types.rs)
- [korvus/src/pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/pipeline.rs)
- [korvus/src/single_field_pipeline.rs](https://github.com/postgresml/korvus/blob/main/korvus/src/single_field_pipeline.rs)
- [README.md](https://github.com/postgresml/korvus/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md)
- [korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
- [korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
# 部署、CLI、扩展与故障排查
## 概览与角色定位
Korvus 的部署、CLI、扩展与故障排查相关代码散布在三个层次：核心 Rust 库顶层模块、绑定生成宏（`rust-bridge`），以及面向 Python/JavaScript 的 CLI 入口。在核心库中，`korvus/src/lib.rs` 声明了 `mod cli`（仅在启用 `python` 或 `javascript` feature 时编译），同时还暴露了 `pub mod migrations` 与若干 `languages` 子模块，这表明 Korvus 在被作为多语言 SDK 启动时，会通过一个本地子进程托管与 Postgres 通信的运行时。
资料来源：[korvus/src/lib.rs]()
Korvus 的扩展性来自于一个名为 `rust-bridge` 的"Rust 到 Rust"转译宏系统：它把一份带 `#[alias]` 与 `#[alias_methods]` 标注的 Rust 源码，自动展开为 PyO3（Python）、Neon（JavaScript）以及 cbindgen（C）三种 FFI 实现。社区中关于"Add Golang"（#6）、"Add PHP"（#9）和"Add .net support"（#24）的请求，本质上都是希望在 `rust-bridge` 中再增加一种 `SupportedLanguage` 分支。
## CLI 与语言绑定机制
Korvus 的 CLI 并不是传统意义上的命令行工具，而是当 `python`/`javascript` feature 启用后随库一同编译的子进程端点。`korvus/src/lib.rs` 中的 `mod cli` 受 `#[cfg(any(feature = "python", feature = "javascript"))]` 条件编译保护，这意味着只有构建绑定版本时才会出现 CLI 进程。
资料来源：[korvus/src/lib.rs]()
语言子模块的分发入口在 `korvus/src/languages/mod.rs` 中：当前支持 `python`、`javascript`、`c` 三种。`korvus/src/collection.rs` 中大量出现的 `#[cfg_attr(feature = "rust_bridge", derive(alias))]` 与 `#[cfg_attr(feature = "rust_bridge", alias_methods(...))]` 注解，正是给 `rust-bridge` 用来生成对应语言包装的"钩子"。
`rust-bridge-macros/src/lib.rs` 暴露了三个核心过程宏：`alias`（为结构体生成语言别名）、`alias_methods`（按属性参数挑选要导出的方法）、`alias_manual`（用于手工定制的别名）。`alias` 宏内部会同时调用 `python::generate_python_alias`、`c::generate_c_alias`、`javascript::generate_javascript_alias` 三个生成器，然后合并到输出 token 流中。
资料来源：[rust-bridge/rust-bridge-macros/src/lib.rs]()
下图展示了单一 Rust 源如何被 `rust-bridge` 转译为多语言 SDK 的工作流：
```mermaid
flowchart LR
A[带 alias / alias_methods
标注的 Rust 源码] --> B[rust-bridge proc macro]
B --> C[PyO3 包装
Python feature]
B --> D[Neon 包装
javascript feature]
B --> E[cbindgen 包装
c feature]
C --> F[CLI / pip 包
korvus-python]
D --> G[CLI / npm 包
korvus-javascript]
E --> H[C 头文件与 .so/.dylib]
```
类型映射规则集中在 `rust-bridge/rust-bridge-macros/src/types.rs` 的 `to_language_string` 方法中：`&mut T` 映射为 `&mut `、`Vec` 映射为 `Vec`、自定义类型追加语言特定后缀（`Python` / `C` / `JavaScript`），从而保证 `Model` 在不同语言侧都暴露为 `ModelPython`、`ModelC`、`ModelJavaScript` 等对应类型。
资料来源：[rust-bridge/rust-bridge-macros/src/types.rs]()
## 部署配置与环境变量
Korvus 的部署强依赖于一个具备 `pgvector` 扩展的 PostgreSQL 实例。各语言示例 README 中都明确要求设置 `KORVUS_DATABASE_URL`：
```
export KORVUS_DATABASE_URL={YOUR DATABASE URL}
```
资料来源：[korvus/python/examples/README.md]()、[korvus/javascript/examples/README.md]()
在运行时层，`korvus/src/lib.rs` 通过 `PgPoolOptions` 异步创建连接池，并使用 `once_cell::sync::Lazy` + `parking_lot::RwLock` 缓存运行时；数据库 schema 升级由 `pub mod migrations` 处理（首次启动时自动执行）。`korvus/src/pipeline.rs` 的 `Pipeline::new` 接受一个 JSON `schema`，并通过 `json_to_schema` 解析成 `FieldAction` 树——`semantic_search`、`splitter`、`full_text_search` 三种动作可以按字段组合，是部署时最容易出错的地方。
## 已知问题与故障排查
社区中反馈最集中的几类问题，几乎都落在本主题的范畴：
| 现象 | 根因 / 排查方向 | 资料来源 |
| --- | --- | --- |
| Korvus Cloud 流水线报 `worker error (os error 11)` | 后端 worker 进程崩溃或被回收；需重启 worker 或重建服务器（#23） | 社区 issue #23 |
| 示例脚本加载 Hugging Face 模型失败 | 缺少 `trust_remote_code: True` 参数（#13） | 社区 issue #13 |
| 希望绑定新增语言 | 当前 `rust-bridge` 仅在 `SupportedLanguage` 中枚举 Python / JavaScript / C（#6, #9, #24） | rust-bridge-macros/src/lib.rs |
| 文档缺失 | 贡献流程见 `CONTRIBUTING.md`，文档改进欢迎 PR | CONTRIBUTING.md |
对于 Hugging Face 模型参数问题，规范的修复方式是在 `semantic_search` 配置中显式传参：
```
"semantic_search": {
"model": "",
"parameters": { "trust_remote_code": true }
}
```
对于 C 绑定场景，`korvus/src/collection.rs` 中 `#[cfg(feature = "c")]` 守卫的 `JsonC`、`PipelineC`、`QueryBuilderC` 是构建产物；如果链接时找不到符号，请确认构建时启用了 `c` feature 并安装了 `cbindgen`。
## 扩展建议
如需新增一门语言绑定，推荐遵循以下步骤（与 `CONTRIBUTING.md` 一致）：
1. 在 `rust-bridge-macros/src/lib.rs` 的 `alias` 宏中加入新的 `generate__alias` 生成器；
2. 在 `types.rs::to_language_string` 中加入该语言的类型映射；
3. 在 `korvus/src/languages/mod.rs` 与 `korvus/src/lib.rs` 中增加对应的 `cfg` 模块声明与 CLI 入口；
4. 在 `korvus//` 目录下补充打包脚本（参考 `korvus/python/` 与 `korvus/javascript/`）。
## See Also
- 项目主页与文档入口：[README.md](https://github.com/postgresml/korvus/blob/main/README.md)
- 贡献流程：[CONTRIBUTING.md](https://github.com/postgresml/korvus/blob/main/CONTRIBUTING.md)
- Rust 桥接宏说明：[rust-bridge/README.md](https://github.com/postgresml/korvus/blob/main/rust-bridge/README.md)
- Python 示例：[korvus/python/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/python/examples/README.md)
- JavaScript 示例：[korvus/javascript/examples/README.md](https://github.com/postgresml/korvus/blob/main/korvus/javascript/examples/README.md)
---
---
## Doramagic 踩坑日志
项目：postgresml/korvus
摘要：发现 17 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add PHP。
## 1. 安装坑 · 来源证据：Add PHP
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add PHP
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/9 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 安全/权限坑 · 来源证据：Add documentation
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Add documentation
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/13 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安装坑 · 来源证据：6 rows with limit 6 and 0 rows with limit 5
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：6 rows with limit 6 and 0 rows with limit 5
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/22 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：Add TypeScript
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add TypeScript
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/17 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。
## 5. 安装坑 · 来源证据：Exception: error returned from database: invalid input value for enum task: "embedding"
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Exception: error returned from database: invalid input value for enum task: "embedding"
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 6. 安装坑 · 来源证据：Hi! My Korvus Cloud pipeline is stuck with a worker error (os error 11) even after creating a new server. Database: pgm…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Hi! My Korvus Cloud pipeline is stuck with a worker error (os error 11) even after creating a new server. Database: pgml_xb9wszjbked8ued — could someone restar…
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/23 | 来源类型 github_issue 暴露的待验证使用条件。
## 7. 安装坑 · 来源证据：High gpu consumption
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：High gpu consumption
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/18 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 8. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/postgresml/korvus | README/documentation is current enough for a first validation pass.
## 9. 运行坑 · 运行可能依赖外部服务
- 严重度：medium
- 证据强度：source_linked
- 发现：项目说明出现 external service/cloud/webhook/database 等运行依赖关键词。
- 对用户的影响：本地安装成功不等于能力可用，外部服务不可用会阻断体验。
- 证据：packet_text.keyword_scan | https://github.com/postgresml/korvus | matched external service / cloud / webhook / database keyword
## 10. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/korvus | last_activity_observed missing
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/postgresml/korvus | no_demo; severity=medium
## 12. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/postgresml/korvus | no_demo; severity=medium
## 13. 安全/权限坑 · 来源证据：Exception: error returned from database: function pgml.transform(task => jsonb, inputs => jsonb[], args => jsonb) does…
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Exception: error returned from database: function pgml.transform(task => jsonb, inputs => jsonb[], args => jsonb) does not exist
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/16 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 14. 安全/权限坑 · 来源证据：FEAT add base url to model config
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：FEAT add base url to model config
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/20 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。
## 15. 安全/权限坑 · 来源证据：content must be a string
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：content must be a string
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/postgresml/korvus/issues/12 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 16. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/korvus | issue_or_pr_quality=unknown
## 17. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/postgresml/korvus | release_recency=unknown