docs: add Feast openGauss integration guide-docs-AtomGit

已开启

docs: add Feast openGauss integration guide #8877

yanfei01-2026创建于 9月20日从yanfei01-2026/docs： docs/feast-opengauss-online-store 合入到 opengauss/docs： master

docs: add Feast openGauss integration guide #8877

已开启

yanfei01-2026创建于 9月20日

从yanfei01-2026/docs docs/feast-opengauss-online-store合入到opengauss/docs master

共 2 个文件变更+204-3

Mdocs/zh/_toc.yaml+9-3

	@@ -20,9 +20,15 @@ sections:
20	- href: ./data_migration_guide/_toc.yaml	20	- href: ./data_migration_guide/_toc.yaml
21	- label: 重要特性	21	- label: 重要特性
22	sections:	22	sections:
23	- - href:	23	+ - label: 向量数据库
24	- upstream: https://atomgit.com/opengauss/openGauss-server/blob/master/src/gausskernel/storage/access/datavec/docs/zh/_toc.yaml	24	+ sections:
25	- path: ./datavec	25	+ - href:
		26	+ upstream: https://atomgit.com/opengauss/openGauss-server/blob/master/src/gausskernel/storage/access/datavec/docs/zh/_toc.yaml
		27	+ path: ./datavec
		28	+ - label: 工具编排使用
		29	+ sections:
		30	+ - label: 知识工程
		31	+ href: ./developer_guide/feast_opengauss_online_store.md
26	- href: ./gv_graph/_toc.yaml	32	- href: ./gv_graph/_toc.yaml
27	- href:	33	- href:
28	upstream: https://atomgit.com/opengauss/openGauss-server/blob/master/docs/zh/resource_pooling/_toc.yaml	34	upstream: https://atomgit.com/opengauss/openGauss-server/blob/master/docs/zh/resource_pooling/_toc.yaml

Adocs/zh/developer_guide/feast_opengauss_online_store.md+195-0

@@ -0,0 +1,195 @@
	1	+# 使用Feast和openGauss构建知识工程在线特征与向量检索
	2	+
	3	+## 概述
	4	+
	5	+在知识工程（Knowledge Engineering）项目中，应用通常需要同时管理结构化在线特征和可检索的向量表示。例如，推荐系统需要按实体读取实时特征，RAG（Retrieval-Augmented Generation）系统需要根据查询向量召回相关文档。Feast负责特征定义、注册和访问接口，openGauss负责在线数据的持久化、事务处理和向量相似性查询。
	6	+
	7	+本方案使用Feast PostgreSQL Online Store接口，并通过轻量适配器连接openGauss：
	8	+
	9	+- openGauss作为online feature store backend，保存结构化特征、实体键、时间戳和更新后的在线值。
	10	+- openGauss作为vector backend，保存文档向量，并使用向量距离操作符完成TopK检索。
	11	+- Feast统一管理Feature View、PushSource和FeatureStore API，应用代码不需要直接拼接upsert SQL。
	12	+- openGauss的向量数据库能力为知识库召回提供存储和检索基础，工具编排层可以在召回结果之上继续调用模型或业务工具。
	13	+
	14	+该文档介绍项目级集成方式。它不是单独的向量数据库安装指南；数据库安装、向量类型和索引能力请参阅[向量数据库特性说明](https://docs.opengauss.org/zh/docs/latest/datavec/datavec_overview.html)。
	15	+
	16	+## 整体架构
	17	+
	18	+典型数据流如下：
	19	+
	20	+```text
	21	+业务应用 / Agent 编排
	22	+ \|
	23	+ \| Feast FeatureStore.push / get_online_features / retrieve_online_documents
	24	+ v
	25	+Feast Feature Repo 与 Online Store 适配层
	26	+ \|
	27	+ \| SQL、事务、实体键、特征值和向量查询
	28	+ v
	29	+openGauss
	30	+ \|-- 结构化在线特征表：实时状态、画像、统计值
	31	+ `-- 向量特征表：文档 embedding、标题和实体标识
	32	+```
	33	+
	34	+在该架构中，Feast解决“特征如何定义和访问”的问题，openGauss解决“数据如何可靠存储和检索”的问题。二者组合后，工具编排流程可以先从openGauss读取实时特征和知识片段，再把结果传递给模型、检索器或其他业务工具。
	35	+
	36	+## 安装与配置
	37	+
	38	+项目需要Python 3.11或更高版本。可从KunpengRAG官方Gitee仓库获取代码，并从
	39	+`Feast_OpenGauss`组件目录安装适配器。
	40	+
	41	+创建虚拟环境前，先确认实际使用的Python解释器版本：
	42	+
	43	+```bash
	44	+python --version
	45	+```
	46	+
	47	+输出版本必须为3.11或更高。
	48	+以下命令中的`python`代表环境中已安装的Python 3.11+解释器；如该解释器使用其他命令名
	49	+或路径，请用实际命令或路径创建虚拟环境，激活后再使用环境中的`python`安装适配器：
	50	+
	51	+```bash
	52	+git clone https://gitee.com/kunpeng_compute/KunpengRAG.git
	53	+cd KunpengRAG/Feast_OpenGauss
	54	+python -m venv .venv
	55	+source .venv/bin/activate
	56	+python -m pip install --upgrade pip
	57	+python -m pip install .
	58	+python -m pip check
	59	+```
	60	+
	61	+`pyproject.toml`会安装兼容的Feast PostgreSQL依赖和`psycopg`驱动。pytest仅用于开发测试，不是运行适配器的安装要求。安装适配器后，使用Feature Repo中的配置文件指定自己的openGauss主机：
	62	+
	63	+```yaml
	64	+online_store:
	65	+ type: feast_opengauss.online_store.OpenGaussOnlineStore
	66	+ host: <OPENGAUSS_HOST>
	67	+ port: <OPENGAUSS_PORT>
	68	+ database: <OPENGAUSS_DATABASE>
	69	+ db_schema: <OPENGAUSS_SCHEMA>
	70	+ user: <OPENGAUSS_USER>
	71	+ password: <OPENGAUSS_PASSWORD>
	72	+ sslmode: disable
	73	+ vector_enabled: true
	74	+ similarity: L2
	75	+```
	76	+
	77	+实际部署时应使用环境变量注入或secret manager提供凭据。不要把真实密码、私网地址或密钥提交到代码仓库。`feature_store.example.yaml`只用于说明字段，不应作为生产运行时配置。
	78	+
	79	+将模板复制为本地配置，并把上面的连接字段填写为自己的数据库信息：
	80	+
	81	+```bash
	82	+cp feature_repo/feature_store.example.yaml feature_repo/feature_store.yaml
	83	+```
	84	+
	85	+在组件目录初始化Feature Repo，然后返回组件目录运行下方示例：
	86	+
	87	+```bash
	88	+cd feature_repo
	89	+feast apply
	90	+cd ..
	91	+```
	92	+
	93	+`feast apply`会根据Feature View和Online Store配置创建或更新所需的在线存储结构。普通应用不需要修改Feast源码，也不需要设置`PYTHONPATH`。
	94	+
	95	+## 结构化在线特征
	96	+
	97	+使用PushSource写入实时特征：
	98	+
	99	+```python
	100	+import pandas as pd
	101	+from feast import FeatureStore
	102	+
	103	+store = FeatureStore(repo_path="feature_repo")
	104	+now = pd.Timestamp.now(tz="UTC")
	105	+store.push(
	106	+ "driver_stats_push_source",
	107	+ pd.DataFrame([
	108	+ {"driver_id": 1, "event_timestamp": now, "score": 2.0, "trips": 11},
	109	+ ]),
	110	+)
	111	+```
	112	+
	113	+按单个实体或批量实体读取：
	114	+
	115	+```python
	116	+result = store.get_online_features(
	117	+ features=["driver_stats:score", "driver_stats:trips"],
	118	+ entity_rows=[{"driver_id": 1}, {"driver_id": 2}],
	119	+).to_dict()
	120	+```
	121	+
	122	+适配器保留Feast的实体键、时间戳、批量读取和事务语义。openGauss侧使用与其兼容的写入upsert语法，应用层不需要直接实现数据库方言。
	123	+
	124	+## 向量特征与知识召回
	125	+
	126	+知识工程流程可以把文档切分、embedding生成和元数据写入同一个Feature Repo。示例中的`document_embeddings` Feature View包含：
	127	+
	128	+- `document_id`实体键，用于把召回结果关联回原始文档；
	129	+- `embedding`三维示例向量，实际项目应按模型输出维度配置；
	130	+- `title`等普通特征，用于展示或后续工具调用。
	131	+
	132	+写入向量特征：
	133	+
	134	+```python
	135	+store.push(
	136	+ "document_embeddings_push_source",
	137	+ pd.DataFrame([
	138	+ {
	139	+ "document_id": 10,
	140	+ "event_timestamp": now,
	141	+ "embedding": [0.1, 0.0, 0.0],
	142	+ "title": "openGauss知识库文档",
	143	+ },
	144	+ ]),
	145	+)
	146	+```
	147	+
	148	+使用查询向量执行TopK检索：
	149	+
	150	+```python
	151	+matches = store.retrieve_online_documents(
	152	+ query=[0.0, 0.0, 0.0],
	153	+ top_k=3,
	154	+ features=["document_embeddings:embedding"],
	155	+ distance_metric="L2",
	156	+).to_dict()
	157	+```
	158	+
	159	+openGauss在这里承担vector backend角色：向量值存储在数据库中，距离计算和排序在数据库侧完成。应用或Agent编排器可以把`document_id`、`title`和召回距离传给下游生成工具，形成“查询理解→向量召回→上下文组织→回答生成”的知识工程流程。
	160	+
	161	+## 工具编排中的职责边界
	162	+
	163	+建议将职责划分如下：
	164	+
	165	+\| 组件 \| 主要职责 \|
	166	+\| --- \| --- \|
	167	+\| 业务应用或Agent \| 接收请求、决定调用哪些工具、组织最终结果 \|
	168	+\| Embedding服务 \| 将文档和用户查询转换为向量 \|
	169	+\| Feast \| 管理实体、Feature View、PushSource和统一访问API \|
	170	+\| openGauss \| 持久化在线特征、向量数据和元数据，并执行事务与相似性查询 \|
	171	+\| 文档或对象存储 \| 保存原始文档和较大附件，数据库保存可检索的标识和必要元数据 \|
	172	+
	173	+openGauss不是Agent编排器本身。它为编排器提供低延迟、可事务更新的在线特征和向量召回能力；编排器根据这些结果继续调用模型、搜索、权限校验或业务系统工具。
	174	+
	175	+## 可靠性与安全注意事项
	176	+
	177	+- 对结构化特征和向量更新使用同一个受控的FeatureStore入口，避免绕过适配器造成事务状态不一致。
	178	+- 连接失败或SQL异常后，应由连接生命周期管理逻辑回滚事务；应用不应复用已经处于失败事务状态的连接。
	179	+- 生产环境使用最小权限账号，并通过安全的凭据注入方式配置密码。
	180	+- 向量维度必须与Feature View声明一致；查询距离类型必须与数据库和项目配置匹配。
	181	+- 验收脚本应在disposable temporary workspace中运行。运行时YAML、registry和测试数据不应覆盖用户已有Feature Repo。
	182	+- 需要验证openGauss版本、向量扩展和索引能力与项目的目标部署版本一致。
	183	+
	184	+## 验证建议
	185	+
	186	+提交或上线前至少验证：
	187	+
	188	+1. `feast apply`能够完成初始化。
	189	+2. 单实体和批量实体读取返回正确顺序。
	190	+3. 相同实体的后续push能够更新在线值。
	191	+4. 向量写入后可以执行TopK查询，返回顺序与数据库侧距离排序一致。
	192	+5. 错误端口、SQL异常和事务异常不会让后续请求持续复用失败状态。
	193	+6. 验收脚本的成功和失败路径都不会修改用户原有的runtime YAML、registry或其他文件。
	194	+
	195	+更多项目配置、验收脚本和示例代码可参考KunpengRAG的`Feast_OpenGauss`目录。