update github action

hank-cp · hank-cp · commit a7679a367d22 · 2025-11-03T19:38:51.000+08:00
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -32,12 +32,17 @@ jobs:
         gosu postgres /usr/lib/postgresql/17/bin/initdb -D /var/lib/postgresql/data
         gosu postgres /usr/lib/postgresql/17/bin/pg_ctl -D /var/lib/postgresql/data start -w
 
+    - name: Start Mock Embedding Server
+      run: |
+        python3 test/mock_embedding_server.py 8080 &
+        sleep 2
+        echo "Mock embedding server started on port 8080"
+
     - name: Setup test environment
-      env:
-        SILICONFLOW_API_KEY: ${{ secrets.SILICONFLOW_API_KEY }}
       run: |
         cp test/.env.example test/.env
-        sed -i "s/your-api-key/$SILICONFLOW_API_KEY/g" test/.env
+        sed -i "s|https://api.siliconflow.cn/v1/embeddings|http://localhost:8080/v1/embeddings|g" test/.env
+        sed -i "s/your-api-key/mock-api-key/g" test/.env
         echo "Test environment configured"
 
     - name: Run test script
diff --git a/README.md b/README.md
@@ -20,13 +20,15 @@ PostgreSQL extension for automatic vector embedding using external embedding ser
 ## Prerequisites
 
 - PostgreSQL 9.5+ with `vector` extension
-- `http` extension
-- `pg_background` extension
-- `pgTAP` extension (for testing)
+- [http](https://github.com/pramsey/pgsql-http) extension
+- [pg_background](https://github.com/vibhorkum/pg_background) extension
+- [pgTAP](https://pgtap.org/documentation.html) extension (for testing)
 
 ## Installation
 
 ```bash
+git clone https://github.com/hank-cp/pg_vector_embedding.git
+cd pg_vector_embedding
 make
 sudo make install
 ```
@@ -95,36 +97,8 @@ LIMIT 10;
 SELECT ve_disable('public', 'documents');
 ```
 
-## Functions
-
-### Configuration
-
-- `ve_config(key TEXT) RETURNS TEXT` - Get configuration value from database settings
-
-### Table Management
-
-- `ve_enable(schema TEXT, table TEXT, info_columns TEXT[], vector_column TEXT)` - Register table for auto-embedding
-- `ve_disable(schema TEXT, table TEXT)` - Unregister table
-
-### Embedding
-
-- `ve_compute_embedding(text TEXT) RETURNS VECTOR` - Compute embedding synchronously
-- `ve_compact_row_data(record ANYELEMENT, columns TEXT[]) RETURNS JSONB` - Extract specified columns to JSON
-- `ve_process_embedding(params JSONB)` - Process embedding for a specific record (used internally)
-
-### Internal Functions
-
-- `ve_trigger()` - Trigger function that launches background embedding tasks
-
 ## Testing
 
-### Run All Tests
-
-```bash
-cd test
-./runner.sh
-```
-
 ### Configure Test Environment
 
 Create `test/.env` file:
@@ -135,6 +109,13 @@ EMBEDDING_API_KEY=your-api-key
 EMBEDDING_MODEL=BAAI/bge-m3
 ```
 
+### Run All Tests
+
+```bash
+cd test
+./runner.sh
+```
+
 ### Test Options
 
 ```bash
@@ -148,10 +129,9 @@ EMBEDDING_MODEL=BAAI/bge-m3
 ## Architecture
 
 1. **Trigger-based Detection**: When a registered table is modified, `ve_trigger()` captures the change
-2. **Column Extraction**: The trigger extracts configured info columns as JSON using `ve_compact_row_data()`
-3. **Background Processing**: A background worker is launched via `pg_background_launch()` to run `ve_process_embedding()`
-4. **API Call**: The background task calls the embedding service via `http` extension using `ve_compute_embedding()`
-5. **Storage**: The returned vector is saved to the configured vector column
+2. **Column Extraction**: The trigger extracts configured info columns as JSON using `ve_compact_row_data()`. Column comments will also be included in the JSON to improve embedding quality.
+3. **Background Processing**: A background worker will be launched to process the embedding request and update the vector column.
+4. **Storage**: The returned vector is saved to the configured vector column. It could be leveraged in vector similarity search, like RAG.
 
 ## Configuration Reference
 
@@ -220,6 +200,4 @@ LIMIT 5;
 2. Ensure table has a primary key (required for tracking records)
 3. Check trigger function exists: `\df ve_trigger`
 
-## License
-
-MIT
+## [License](LICENSE)
diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -2,10 +2,13 @@
 [![Tests](https://github.com/hank-cp/pg_vector_embedding/actions/workflows/test.yml/badge.svg)](https://github.com/hank-cp/pg_vector_embedding/actions/workflows/test.yml)
 ![GitHub](https://img.shields.io/github/license/hank-cp/pg_vector_embedding.svg)
 ![GitHub last commit](https://img.shields.io/github/last-commit/hank-cp/pg_vector_embedding.svg)
+
 # pg_vector_embedding
 
 PostgreSQL 扩展，用于使用外部嵌入服务自动生成向量嵌入。
 
+[English Documentation](README.md)
+
 ## 特性
 
 - 通过数据库设置进行全局嵌入服务配置
@@ -17,13 +20,15 @@ PostgreSQL 扩展，用于使用外部嵌入服务自动生成向量嵌入。
 ## 前置要求
 
 - PostgreSQL 9.5+ 及 `vector` 扩展
-- `http` 扩展
-- `pg_background` 扩展
-- `pgTAP` 扩展（用于测试）
+- [http](https://github.com/pramsey/pgsql-http) 扩展
+- [pg_background](https://github.com/vibhorkum/pg_background) 扩展
+- [pgTAP](https://pgtap.org/documentation.html) 扩展（用于测试）
 
 ## 安装
 
 ```bash
+git clone https://github.com/hank-cp/pg_vector_embedding.git
+cd pg_vector_embedding
 make
 sudo make install
 ```
@@ -40,12 +45,10 @@ CREATE EXTENSION pg_vector_embedding CASCADE;
 
 ```sql
 -- 设置数据库级别配置
-ALTER DATABASE your_database SET pg_vector_embedding.embedding_url = 'https://api.siliconflow.cn/v1/embeddings';
-ALTER DATABASE your_database SET pg_vector_embedding.embedding_api_key = 'your-api-key';
-ALTER DATABASE your_database SET pg_vector_embedding.embedding_model = 'BAAI/bge-m3';
-
--- 重新连接以应用配置
-\c
+ALTER SYSTEM SET pg_vector_embedding.embedding_url = 'https://api.siliconflow.cn/v1/embeddings';
+ALTER SYSTEM SET pg_vector_embedding.embedding_api_key = 'your-api-key';
+ALTER SYSTEM SET pg_vector_embedding.embedding_model = 'BAAI/bge-m3';
+-- 重启 Postgres 以应用设置
 ```
 
 ### 3. 创建带向量列的表
@@ -74,7 +77,7 @@ SELECT ve_enable(
 
 ```sql
 INSERT INTO documents (title, content) 
-VALUES ('PostgreSQL 扩展', '学习如何构建强大的 PostgreSQL 扩展');
+VALUES ('PostgreSQL Extensions', 'Learn how to build powerful PostgreSQL extensions');
 ```
 
 嵌入将通过 `pg_background` 异步计算并存储在 `embedding` 列中。
@@ -84,7 +87,7 @@ VALUES ('PostgreSQL 扩展', '学习如何构建强大的 PostgreSQL 扩展');
 ```sql
 -- 为搜索查询计算嵌入
 SELECT * FROM documents
-ORDER BY embedding <-> ve_compute_embedding('{"title": "PostgreSQL", "content": "扩展"}'::text)
+ORDER BY embedding <-> ve_compute_embedding('{"title": "PostgreSQL", "content": "extensions"}'::text)
 LIMIT 10;
 ```
 
@@ -94,36 +97,8 @@ LIMIT 10;
 SELECT ve_disable('public', 'documents');
 ```
 
-## 函数
-
-### 配置
-
-- `ve_config(key TEXT) RETURNS TEXT` - 从数据库设置获取配置值
-
-### 表管理
-
-- `ve_enable(schema TEXT, table TEXT, info_columns TEXT[], vector_column TEXT)` - 注册表以启用自动嵌入
-- `ve_disable(schema TEXT, table TEXT)` - 注销表
-
-### 嵌入
-
-- `ve_compute_embedding(text TEXT) RETURNS VECTOR` - 同步计算嵌入
-- `ve_compact_row_data(record ANYELEMENT, columns TEXT[]) RETURNS JSONB` - 提取指定列为 JSON
-- `ve_process_embedding(params JSONB)` - 为特定记录处理嵌入（内部使用）
-
-### 内部函数
-
-- `ve_trigger()` - 触发器函数，启动后台嵌入任务
-
 ## 测试
 
-### 运行所有测试
-
-```bash
-cd test
-./runner.sh
-```
-
 ### 配置测试环境
 
 创建 `test/.env` 文件：
@@ -134,6 +109,13 @@ EMBEDDING_API_KEY=your-api-key
 EMBEDDING_MODEL=BAAI/bge-m3
 ```
 
+### 运行所有测试
+
+```bash
+cd test
+./runner.sh
+```
+
 ### 测试选项
 
 ```bash
@@ -147,10 +129,9 @@ EMBEDDING_MODEL=BAAI/bge-m3
 ## 架构
 
 1. **基于触发器的检测**：当注册的表被修改时，`ve_trigger()` 捕获变更
-2. **列提取**：触发器使用 `ve_compact_row_data()` 将配置的信息列提取为 JSON
-3. **后台处理**：通过 `pg_background_launch()` 启动后台工作进程来运行 `ve_process_embedding()`
-4. **API 调用**：后台任务通过 `http` 扩展使用 `ve_compute_embedding()` 调用嵌入服务
-5. **存储**：返回的向量保存到配置的向量列中
+2. **列提取**：触发器使用 `ve_compact_row_data()` 将配置的信息列提取为 JSON。列注释也将包含在 JSON 中以提高嵌入质量。
+3. **后台处理**：将启动后台工作进程来处理嵌入请求并更新向量列。
+4. **存储**：返回的向量保存到配置的向量列中。它可以在向量相似性搜索中使用，例如 RAG。
 
 ## 配置参考
 
@@ -187,15 +168,15 @@ SELECT ve_enable('public', 'articles', ARRAY['title', 'content'], 'embedding');
 
 -- 3. 插入数据（嵌入在后台自动计算）
 INSERT INTO articles (title, content) VALUES 
-    ('PostgreSQL 扩展', '学习如何构建强大的 PostgreSQL 扩展'),
-    ('向量搜索', '使用 pgvector 实现语义搜索');
+    ('PostgreSQL Extensions', 'Learn how to build powerful PostgreSQL extensions'),
+    ('Vector Search', 'Implementing semantic search with pgvector');
 
 -- 4. 等待后台处理（或检查嵌入是否就绪）
 SELECT COUNT(*) FROM articles WHERE embedding IS NOT NULL;
 
 -- 5. 执行相似度搜索
 WITH search_query AS (
-    SELECT ve_compute_embedding('{"title": "PostgreSQL", "content": "教程"}'::text) AS query_embedding
+    SELECT ve_compute_embedding('{"title": "PostgreSQL", "content": "tutorial"}'::text) AS query_embedding
 )
 SELECT id, title, embedding <-> query_embedding AS distance
 FROM articles, search_query
@@ -219,50 +200,4 @@ LIMIT 5;
 2. 确保表有主键（用于跟踪记录时必需）
 3. 检查触发器函数是否存在：`\df ve_trigger`
 
-## 特殊功能
-
-### 列注释支持
-
-`ve_compact_row_data()` 函数会自动提取列注释并添加到嵌入内容中，以提高嵌入准确性：
-
-```sql
-CREATE TABLE products (
-    id SERIAL PRIMARY KEY,
-    name TEXT,
-    description TEXT,
-    embedding VECTOR(1024)
-);
-
-COMMENT ON COLUMN products.name IS '产品名称';
-COMMENT ON COLUMN products.description IS '产品描述';
-
-SELECT ve_enable('public', 'products', ARRAY['name', 'description'], 'embedding');
-
--- 插入数据时，生成的 JSON 会包含列注释：
--- {"name": "产品名称: 笔记本电脑", "description": "产品描述: 高性能办公笔记本"}
-INSERT INTO products (name, description) VALUES ('笔记本电脑', '高性能办公笔记本');
-```
-
-### JSON/JSONB/数组字段支持
-
-函数会自动识别 JSON、JSONB 和数组类型字段，并保持其原始结构：
-
-```sql
-CREATE TABLE events (
-    id SERIAL PRIMARY KEY,
-    title TEXT,
-    tags TEXT[],
-    metadata JSONB,
-    embedding VECTOR(1024)
-);
-
-SELECT ve_enable('public', 'events', ARRAY['title', 'tags', 'metadata'], 'embedding');
-
--- tags 作为 JSON 数组，metadata 作为 JSON 对象保存，而不是字符串
-INSERT INTO events (title, tags, metadata) VALUES 
-    ('会议', ARRAY['技术', 'PostgreSQL'], '{"location": "北京", "duration": 120}');
-```
-
-## 许可证
-
-MIT
+## [许可证](LICENSE)
