tencentdb_ai.add_incr_autoembedding_task(
    schema_name    NAME,        -- 表所在 schema
    table_name     NAME,        -- 表名
    source_columns NAME[],      -- 源文本列名数组
    model_name     NAME,        -- 嵌入模型名称
    target_column  NAME  DEFAULT NULL,   -- 目标向量列名
    index_method   TEXT  DEFAULT 'hnsw', -- 向量索引方法
    options        JSONB DEFAULT '{}'    -- 扩展选项
) RETURNS BIGINT

-- 单列嵌入：对 content 列创建嵌入，目标列自动命名为 content_embedding
SELECT tencentdb_ai.add_incr_autoembedding_task(
    'public', 'articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b'
);

-- 多列嵌入：合并 title + body 生成嵌入，显式指定目标列和索引方法
SELECT tencentdb_ai.add_incr_autoembedding_task(
    'public', 'articles',
    ARRAY['title', 'body'],
    'kinfra-text-embedding-0.6b',
    target_column => 'doc_embedding',
    index_method => 'hnsw'
);

-- 覆盖向量维度（当 model_list 中未设置 embedding_dim 时）
SELECT tencentdb_ai.add_incr_autoembedding_task(
    'public', 'articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b',
    options => '{"vector_dim": 1024}'
);

tencentdb_ai.add_backfill_autoembedding_task(
    schema_name    NAME,        -- 表所在 schema
    table_name     NAME,        -- 表名
    source_columns NAME[],      -- 源文本列名数组
    model_name     NAME,        -- 嵌入模型名称
    target_column  NAME  DEFAULT NULL,   -- 目标向量列名
    start_now      BOOL  DEFAULT false,  -- 是否立即开始回填
    options        JSONB DEFAULT '{}'    -- 扩展选项
) RETURNS BIGINT

-- 先创建增量任务（自动创建向量列 + 触发器）
SELECT tencentdb_ai.add_incr_autoembedding_task(
    'public', 'articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b'
);

-- 再创建存量任务，立即回填历史数据
SELECT tencentdb_ai.add_backfill_autoembedding_task(
    'public', 'articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b',
    start_now => true
);

-- 也可以先注册任务（默认 start_now 为 false），稍后手动触发
SELECT tencentdb_ai.add_backfill_autoembedding_task(
    'public', 'articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b'
);

-- 稍后手动启动
SELECT tencentdb_ai.run_backfill_autoembedding_task(1);

tencentdb_ai.drop_incr_autoembedding_task(task_id BIGINT) RETURNS VOID
tencentdb_ai.drop_backfill_autoembedding_task(task_id BIGINT) RETURNS VOID

-- 删除增量任务
SELECT tencentdb_ai.drop_incr_autoembedding_task(1);

-- 删除存量任务
SELECT tencentdb_ai.drop_backfill_autoembedding_task(2);

tencentdb_ai.run_backfill_autoembedding_task(
    task_id    BIGINT,           -- 存量任务 ID
    batch_size INT DEFAULT 8192  -- 后台工作进程每轮扫描入队的最大行数
) RETURNS VOID

-- 手动启动存量回填
SELECT tencentdb_ai.run_backfill_autoembedding_task(1);

-- 查看所有任务状态
SELECT task_kind, task_id, schema_name, table_name, 
       target_column, status, backfill_state, 
       pending, backfilled_rows, failed_count
FROM tencentdb_ai.autoembedding_status
ORDER BY task_id;

-- 查看最近的错误
SELECT task_kind, task_id, row_id, error_message, created_at
FROM tencentdb_ai.autoembedding_error
ORDER BY created_at DESC
LIMIT 10;

-- 安装扩展（pgmq / pgvector 通过 CASCADE 自动安装）
CREATE EXTENSION IF NOT EXISTS tencentdb_ai CASCADE;

-- 注册嵌入模型（json_path 必须为 NULL）
SELECT tencentdb_ai.add_model('kinfra-text-embedding-0.6b', NULL, NULL, NULL, 'tokenhub');
SELECT tencentdb_ai.update_model_attr('kinfra-text-embedding-0.6b', 'api_key', 'your_api_key');

-- 设置嵌入维度（必须，否则创建任务时需通过 options.vector_dim 指定）
UPDATE tencentdb_ai.model_list SET embedding_dim = 1024 WHERE model_name = 'kinfra-text-embedding-0.6b';

-- 创建知识库表
CREATE TABLE kb_articles (
    id      bigserial PRIMARY KEY,
    title   text,
    content text
);

-- 插入测试数据
INSERT INTO kb_articles (title, content) VALUES
    ('PostgreSQL 简介', 'PostgreSQL 是一个功能强大的开源对象关系数据库系统...'),
    ('向量数据库', '向量数据库是一种专门用于存储和检索高维向量的数据库系统...'),
    ('RAG 技术', '检索增强生成（RAG）是一种结合检索和生成能力的 AI 技术...');

-- 创建增量任务：自动添加 content_embedding 列，创建触发器
SELECT tencentdb_ai.add_incr_autoembedding_task(
    'public', 'kb_articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b'
) AS incr_task_id;

-- 创建存量任务：立即回填已有的 3 行历史数据
SELECT tencentdb_ai.add_backfill_autoembedding_task(
    'public', 'kb_articles',
    ARRAY['content'],
    'kinfra-text-embedding-0.6b',
    start_now => true
) AS backfill_task_id;

-- 等待后台进程处理（默认每 1 秒轮询一次）
SELECT pg_sleep(3);

-- 检查存量回填进度
SELECT backfill_state, backfilled_rows
FROM tencentdb_ai.autoembedding_status
WHERE task_kind = 'backfill';

 backfill_state | backfilled_rows
----------------+-----------------
 done           |               3
(1 row)

-- 验证向量已生成
SELECT id, title, 
       content_embedding IS NOT NULL AS has_embedding,
       vector_dims(content_embedding) AS dims
FROM kb_articles
ORDER BY id;

 id |      title      | has_embedding | dims
----+-----------------+---------------+------
  1 | PostgreSQL 简介 | t             | 1024
  2 | 向量数据库      | t             | 1024
  3 | RAG 技术        | t             | 1024
(3 rows)

-- 查看任务状态
SELECT * FROM tencentdb_ai.autoembedding_status;

-- 插入新数据，触发器自动入队
INSERT INTO kb_articles (title, content) VALUES
    ('嵌入模型', '嵌入模型是将文本转换为向量表示的机器学习模型...');

-- 等待后台进程处理
SELECT pg_sleep(2);

-- 验证新数据向量已生成
SELECT id, title, content_embedding IS NOT NULL AS has_embedding
FROM kb_articles
ORDER BY id;

 id |      title      | has_embedding
----+-----------------+---------------
  1 | PostgreSQL 简介 | t
  2 | 向量数据库      | t
  3 | RAG 技术        | t
  4 | 嵌入模型        | t
(4 rows)

-- 检查队列积压
SELECT task_kind, task_id, pending
FROM tencentdb_ai.autoembedding_status
WHERE pending > 0;

-- 查看错误详情
SELECT * FROM tencentdb_ai.autoembedding_error
ORDER BY created_at DESC LIMIT 20;