tencent cloud

TencentDB for PostgreSQL

DocumentationTencentDB for PostgreSQLAI CapabilitiesAI Large Model Invocationtencentdb_ai Model Backend Migration Guide

tencentdb_ai Model Backend Migration Guide

Download
Focus Mode
Font Size
Last updated: 2026-08-20 17:45:11
AI-Translated

Background

The original Hunyuan Large Model and Knowledge Engine atomic capability DeepSeek API no longer adds new model capabilities and has stopped accepting new model service purchases. All subsequent capabilities will be migrated to the Large Model Service Platform TokenHub (purchased services can continue to be used before service termination; the specific termination time is subject to the platform decommissioning announcement, see TokenHub Platform Migration Documentation).
The hunyuan and lkeap model backends of the tencentdb_ai plugin are deprecated along with the platform. You are recommended to migrate your in-use models to the tokenhub backend. This document describes the migration method.

Migration Overview

Backend Differences Comparison

Item
hunyuan/lkeap Backend (Deprecated)
tokenhub Backend (Recommended)
Authentication Method
SecretId / SecretKey (TC3 signature)
api_key(Bearer)
Response Protocol
TencentCloud API format ($.Response...)
OpenAI-compatible format ($.choices..., $.data...)
version / region
Required (for example, 2023-09-01, ap-guangzhou)
Not required. Pass NULL during registration.
Model Name
The registered name is the invocation name.
model_name is only an alias within the plugin. The model identifier actually sent by the plugin to the TokenHub gateway is determined by real_model_name, which must be set to the service ID of a model enabled in the console's "Online Inference" section (for example, hy3). Otherwise, the error The model or service ID xxx does not exist is reported.

Feature Impact Overview

Component Feature
hunyuan / lkeap
tokenhub
Migration Action
Dialogue chat_completions
✓
✓
yaml Configuration change only
Fixed scenarios (sentiment / summarize / generate_text / generate_int / generate_double / generate_boolean)
✓
✓
yaml Configuration change only
NL2SQL(generate_query)
✓
✓
yaml Configuration change only
Text vector get_embedding
✓
✓
yaml Change configuration + Re-embed existing data
RAG(retrieve / rag)
✓
✓
yaml Change configuration + Re-embed existing data
Automatic vector column autoembedding
✓
✓
yaml Rebuild tasks + Re-embed existing data
Text reranking run_rerank
lkeap only
×
yaml No migration path. Use vector search and reranking as an alternative.

Preparations

Opening TokenHub Service and Creating an API Key

1. Log in to the TokenHub console and activate the required model services.
2. Create an API Key (starting with sk-) in API Key Management. The SecretId/SecretKey from the original platform are not interchangeable with the API Key, so you must create a new one.

Selecting a New Model

For the complete list and specifications of available models on TokenHub, see TokenHub Model List and select the models as needed. Overview of common model types:
Type
Model (Service ID)
Key Specifications
Language model
hy3, glm-5.2, deepseek-v4-flash, deepseek-v4-pro, kimi-k2.7, minimax-m3, and so on
Context 256k - 1M, see the model list for details.
Vector model
kinfra-text-embedding-0.6b
1024 dimensions, 32k context, lightweight and low-cost
Vector model
kinfra-text-embedding-4b
2560 dimensions, 32k context, high-quality search
Note:
The multimodal vector models (kinfra-vl-embedding-2b / 8b) on the TokenHub platform use a different invocation protocol than the text vector models. Therefore, the plugin's get_embedding cannot be called. Do not register or use these models.
The platform may occasionally return HTTP 504 (upstream timeout). Simply retry the request.

Three Key Points of Plugin Configuration Differences

1. Authentication: Replace SecretId/SecretKey with api_key:
SELECT tencentdb_ai.update_model_attr('<model_name>', 'api_key', 'sk-********');
2. json_path: For chat models, change the format from Hunyuan format '$.Response.Choices[*].Message.Content' to OpenAI format '$.choices[0].message.content'. For embedding models, json_path must always be NULL (the response is parsed by get_embedding).
3. version / region: Not required for the tokenhub backend. Pass NULL when registering a new model. Any existing version / region values on registered models have no effect on the tokenhub backend, so there is no need to clear them.

Feature Migration Guide

Migration of Conversational Features

Features involved: chat_completions, sentiment, summarize, generate_text, generate_int, generate_double, generate_boolean, generate_query.
Chat invocations are stateless. You only need to update the model registration information, and the business SQL does not need to be modified. The in-place update method is recommended (the model name remains unchanged):
-- Using the old model my-chat (originally the hunyuan backend) as an example, update the four attributes in sequence.
SELECT tencentdb_ai.update_model_attr('my-chat', 'backend_type', 'tokenhub');
SELECT tencentdb_ai.update_model_attr('my-chat', 'real_model_name', 'hy3');   -- Replace with the service ID you selected
SELECT tencentdb_ai.update_model_attr('my-chat', 'json_path', '$.choices[0].message.content');
SELECT tencentdb_ai.update_model_attr('my-chat', 'api_key', 'sk-********');

-- Verification: The model name in the business SQL remains unchanged and is directly usable.
SELECT tencentdb_ai.chat_completions('my-chat', 'Hello, introduce yourself in one sentence.');
                                        answer
--------------------------------------------------------------------------------------
 Hello, I am Hunyuan, a large language model developed by Tencent. I can answer your questions, provide information, and assist with various tasks.
(1 row)
If you want to keep the old configuration for comparison and verification, you can also register a new model separately (Path B) and then replace the model names in your business SQL one by one:
SELECT tencentdb_ai.add_model('hy3', NULL, NULL, '$.choices[0].message.content'::jsonpath, 'tokenhub');
SELECT tencentdb_ai.update_model_attr('hy3', 'api_key', 'sk-********');

Migration of embedding Features

Features involved: get_embedding, as well as retrieve, rag, and autoembedding, which depend on it.
Attention:
Replacing the embedding model means replacing the vector space. Even if the new and old models have the same dimensions, vectors generated by the old model cannot be compared with those generated by the new model. Therefore, all vector data in the existing knowledge base must be re-embedded with the new model; otherwise, the search results will be incorrect.

Step 1: Registering a New embedding Model

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', 'sk-********');

Step 2: Re-embedding Existing Data

When the new and old models have the same dimensions (for example, hunyuan-embedding 1024 dimensions → kinfra-text-embedding-0.6b 1024 dimensions), the column definitions remain unchanged. Simply update directly:
UPDATE kb_docs SET embedding = (
    SELECT e::vector(1024)
    FROM tencentdb_ai.get_embedding('kinfra-text-embedding-0.6b', ARRAY[chunk]) AS e
);
When the data volume is large, it is recommended to execute in batches by primary key range to avoid timeouts in a single batch or triggering platform rate limiting.
When the new and old models have different dimensions (for example, switching to kinfra-text-embedding-4b with 2560 dimensions), you must first clear the vector column, modify the column dimensions, and then re-embed:
UPDATE kb_docs SET embedding = NULL;
ALTER TABLE kb_docs ALTER COLUMN embedding TYPE vector(2560);
UPDATE kb_docs SET embedding = (
    SELECT e::vector(2560)
    FROM tencentdb_ai.get_embedding('kinfra-text-embedding-4b', ARRAY[chunk]) AS e
);
After re-embedding is complete, if an ivfflat / hnsw index is built on the vector column, it is recommended to reindex to ensure recall quality:
REINDEX INDEX <index_name>;

Step 3: Rebuilding Tasks for autoembedding Users

For tables that use automatic vector column maintenance, you need to rebuild the task and re-embed by following the process below:
-- 1. Delete the old task (the task ID can be queried through the tencentdb_ai.autoembedding_status view)
SELECT tencentdb_ai.drop_incr_autoembedding_task(<old_task_id>);

-- 2. Clear the old vectors (if the model registration has also been changed, complete update_model_attr first)
UPDATE notes SET body_embedding = NULL;

-- 3. Re-register the incremental task
SELECT tencentdb_ai.add_incr_autoembedding_task('public', 'notes', ARRAY['body']::name[], 'kinfra-text-embedding-0.6b');

-- 4. Register a backfill task to re-embed existing data
SELECT tencentdb_ai.add_backfill_autoembedding_task('public', 'notes', ARRAY['body']::name[], 'kinfra-text-embedding-0.6b', NULL, true);

-- 5. View the backfill progress
SELECT task_kind, status, backfill_state, backfilled_rows, failed_count
FROM tencentdb_ai.autoembedding_status;
 task_kind | status  | backfill_state | backfilled_rows | failed_count
-----------+---------+----------------+-----------------+--------------
 incr      | enabled |                |                 |            0
 backfill  |         | done           |               2 |            0
(2 rows)

Migration Notes for run_rerank

TokenHub currently does not provide a rerank model. The plugin's run_rerank supports only the lkeap backend, with no migration path available. It is recommended to use vector search with distance-based sorting as an alternative:
SELECT chunk, distance
FROM tencentdb_ai.retrieve(
    'kinfra-text-embedding-0.6b', 'your query',
    'public', 'kb_docs', 'chunk', 'embedding', 10, 'cosine'
)
ORDER BY distance, chunk;

Previous Topic: tencentdb_ai RAGNext Topic: High-Performance Vector Search with pgvectorscale (DiskANN)

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback