tencent cloud

Tencent Cloud DataBuddy

DocumentaçãoTencent Cloud DataBuddyData ScienceFeature ManagementBest Practices and Exception Troubleshooting

Best Practices and Exception Troubleshooting

Baixar
Modo Foco
Tamanho da Fonte
Última atualização: 2026-10-09 16:14:32
Traduzido por IA
This document summarizes the key best practices across the full DataBuddy feature management lifecycle (table creation → training → inference → online publishing), along with the most common exception types, an error quick-reference, and a troubleshooting checklist, helping you avoid frequent pitfalls and quickly locate issues.

Best Practices

1. Data Type Governance: Unified cast to double before data is written

The feature engineering SDK does not recognize the decimal(p, s) type. If a decimal column exists in the feature table, fe.log_model will be unable to infer the model signature (signature) when logging the model, which may lead to type mismatches between online and offline inference, or even the absence of a signature section in the MLmodel file.
Best practice: Before writing to the feature table, cast all decimal columns to double, and encapsulate this processing into a reusable utility function that is called consistently across all table creation and write pipelines. Timestamp columns should remain as time types and must not be converted to strings, otherwise they cannot be used as timestamp keys.

2. Pipeline Iron Rule: Preprocessing Must Be Encapsulated in sklearn.Pipeline

All preprocessing steps (OneHotEncoder, StandardScaler, custom transforms, and so on) must be encapsulated into an sklearn.Pipeline, and the entire Pipeline must be passed as the model to fe.log_model.
Do not use pd.get_dummies / manually call StandardScaler.fit_transform outside the Pipeline before model.fit(...): external preprocessing steps will not be serialized into MLmodel. During inference, the SDK looks up raw string columns from the feature table and feeds them to a bare model that only recognizes post-OHE column names, which at best raises Feature names unseen at fit time and at worst silently outputs the training set mean for all samples.
from sklearn.pipeline import Pipeline
from sklearn.compose import ColumnTransformer
from sklearn.preprocessing import OneHotEncoder, StandardScaler

preprocessor = ColumnTransformer(transformers=[
    ("cat", OneHotEncoder(handle_unknown="ignore"), ["<categorical_feature>"]),
    ("num", StandardScaler(), ["<numeric_feature>"]),
])
model = Pipeline(steps=[("preprocessor", preprocessor), ("clf", <estimator>)])

3. Model Logging: Must Use fe.log_model and Pass training_set

You must use fe.log_model instead of mlflow.<flavor>.log_model: only the former packages FeatureSpec into MLmodel, otherwise score_batch cannot find the feature source.
You must pass training_set and enable infer_input_example=True: the model signature and input_example are automatically inferred by the SDK, which is a prerequisite for deploying an online inference service.
Do not manually call infer_signature(...) or manually pass input_example=..., otherwise it will misalign with the original columns of feature_spec and pollute the contract.

4. Point-in-time Consistency: Explicitly Include the Timestamp Column

When a timestamp_lookup_key is declared during training, it is strongly recommended that the input df of score_batch explicitly include a timestamp column with the same name to ensure point-in-time consistency. If it is not included, the SDK automatically injects current_timestamp() to fetch the latest visible features, which is equivalent to predicting historical samples with today's features and is semantically imprecise.
To limit the lookback time range, use lookback_window (a non-negative datetime.timedelta) in FeatureLookup, and it must be used together with timestamp_lookup_key.

5. Naming Conventions: Consistently Use Three-Part Fully Qualified Names

Use the three-part fully qualified names catalog.schema.table / catalog.schema.model_name consistently when referencing feature tables and registering models. This avoids the side effects of relying on the default catalog and eliminates code changes when a migration to a different workspace is performed.

Exception Classification

Exception Type
Trigger Scenario
Handling Recommendation
ImportError
The MLflow version in the runtime environment is lower than the SDK requirement.
Install the SDK with the mlflow3 extra, or upgrade MLflow to the required version.
EnvironmentError(wedata.common.utils.env_utils)
Required environment variables are not set (project ID, region, engine name, and so on).
Run in the DataBuddy Notebook kernel, or configure the corresponding environment variables locally.
KeyError
Temporary key environment variable missing.
Run in the DataBuddy Notebook kernel, or configure the corresponding environment variables locally.
ValueError
Business parameter validation failed.
Correct the parameters based on the error message.
RuntimeError
Failure to call underlying TencentCloud APIs, compute resources, or connections
Check the request_id in the error message, and troubleshoot with the DataBuddy console.
TencentCloudSDKException
Error returned when TencentCloud APIs are called (authentication failure, resource not found, rate limiting, and so on).
Contact platform support based on the code / message / request_id.
IllegalArgumentException / Exception(PySpark)
Spark SQL execution failed (DDL, write, read).
Troubleshoot Spark logs and table permissions.

ValueError Quick Reference

ValueError is usually caused by invalid parameters and can be quickly fixed by checking the error message:
Error Message (Excerpt)
Scenario
Fix method
name must be a non-empty string
Passing an empty string as the table name or database name.
Check parameters.
name '...' contains too many segments
The number of segments in the table name exceeds 3.
Use the catalog.schema.table three-level format or a shorter one.
database_name '...' contains too many segments
The number of segments in the database name exceeds 2.
Use the catalog.schema two-level format or a single-level name.
catalog_name '...' conflicts with catalog '...'
The explicit catalog_name is inconsistent with the parsed result of the multi-segment name.
Keep them consistent, or pass only one of them.
Primary keys have duplicates: [...]
Duplicate primary keys in create_table
Remove duplicates; pass a list instead of a string for composite primary keys.
Engine type ... is not supported
engine_type is not within the supported enum values.
Use EngineTypes.ICEBERG_ENGINE or EngineTypes.HIVE_ENGINE.
Invalid write mode '...'
Invalid value for mode in write_table
Use append or overwrite.
Streaming write requires checkpoint_location parameter
Streaming write does not pass checkpoint_location
Explicitly specify the checkpoint path.
table '...' not exists
The table to read, write, delete, or tag does not exist.
Run create_table first, or check the catalog / database / table name.
properties must be a non-empty dictionary
No valid key or value provided when tags are set.
Pass a non-empty key and value.
All properties are reserved and cannot be set: [...]
Tag key conflicts with a system-reserved field (such as primary key or timestamp key).
Use a non-reserved key.
Either 'feature_spec' or 'feature_lookups' must be provided, but not both.
Both or neither of the two parameters are passed to create_training_set
Choose either one.
Invalid feature_spec format
feature_spec is not in the three-segment format.
Change it to catalog.schema.spec_name.
FeatureLookup must specify a table_name
FeatureLookup.table_name is empty.
Explicitly specify the table name.
When table_name '...' is a single-level name, both 'catalog_name' and 'database_name' must be provided.
FeatureLookup uses a single-level table name without specifying catalog / database.
Use a three-level table name (recommended), or explicitly pass catalog_name + database_name.
When table_name '...' is a two-level name (schema.table), 'catalog_name' must be provided.
FeatureLookup uses a two-level table name but does not pass catalog.
Provide catalog_name or use a three-level name instead.
Unexpected lookback_window value: ...
lookback_window is not used with timestamp_lookup_key
Set timestamp_lookup_key at the same time.
only non-negative datetime.timedelta allowed.
lookback_window is not a timedelta or is negative.
Use a non-negative datetime.timedelta(...).
Setting multiple timestamp lookup keys is not supported.
A multi-element list is passed to timestamp_lookup_key
Pass only a single column name (str) or a single-element list.
cloud_secret_id is empty / cloud_secret_key is empty
Temporary key not injected.
Check the authentication environment variables.

RuntimeError Quick Reference

RuntimeError is usually related to compute resources, data source connections, or TencentCloud API calls. The error message typically includes a request_id for easier troubleshooting:
Error Message (Excerpt)
Scenario
Fix method
Failed to delete table '...'
Failed to execute DROP TABLE at the underlying layer.
Check the exception cause, table locks/permissions.
Failed to modify properties for table '...'
Failed to modify table tags.
Check the exception cause.
Failed to list compute resources: no compute resources found
No running compute resource groups in the workspace.
Create/enable a data compute resource group in the DataBuddy console.
Unable to get compute resource basic info
Missing basic information for the resource group.
Contact the workspace administrator.
Failed to list connections: no connections found
No PostgreSQL connection in the workspace when online tables are published.
Create a PostgreSQL connection in the console.
Failed to create online table '...'
Failed to create an online table by calling publish_table
Contact platform support with the request_id.
Failed to drop online table
Failed to execute drop_online_table
Same as above.
TargetPath.CatalogName cannot be empty
publish_table lacks online Catalog information in specific versions/environments.
Pass the online_catalog_name (for the specific name, refer to the online Catalog configured in the workspace).

End-to-End Troubleshooting Checklist

The following table summarizes the most common pitfalls across the entire workflow from table creation to online deployment, organized by symptom → root cause → solution:
Symptom
Root cause
Solution
No signature section in the MLmodel file.
The feature table contains a decimal(p, s) column, which is not supported by SDK type mapping.
cast all decimal columns to double before writing.
log_model fails to infer signature / score_batch column mismatch.
Used the native mlflow.<flavor>.log_model, or manually passed signature / input_example
Use fe.log_model(..., training_set=..., infer_input_example=True) instead.
ImportError: ... mlflow >= ...
The MLflow version in the environment is too low.
Reinstall the SDK with the mlflow3 extra.
EnvironmentError / KeyError
Missing environment variables in local debugging.
Run in DataBuddy Notebook, or configure the corresponding environment variables locally.
When table_name '...' is a single-level name ...
FeatureLookup uses a single-level table name without specifying catalog / database.
Use a three-level table name (recommended), or explicitly pass catalog_name + database_name
Unexpected lookback_window value ...
lookback_window is not used with timestamp_lookup_key
Set timestamp_lookup_key at the same time.
only non-negative datetime.timedelta allowed.
lookback_window is not a timedelta or is negative.
Use a non-negative datetime.timedelta(days=N)
Failed to list compute resources: no compute resources found
No running compute resource groups in the workspace.
Start a data compute resource group in the DataBuddy console.
Failed to list connections: no connections found
No PostgreSQL connection when online tables are published.
First create a PostgreSQL connection in the console.
TargetPath.CatalogName cannot be empty
publish_table lacks online Catalog information in specific versions/environments.
Pass the online_catalog_name (for the name, refer to the online Catalog configured in the workspace).
Primary keys have duplicates
Duplicate primary keys in create_table
Remove duplicates; pass a list instead of a string for composite primary keys.
Streaming write requires checkpoint_location parameter
Streaming write_table does not pass checkpoint.
Explicitly pass checkpoint_location
score_batch throws schema mismatch.
The inference DataFrame type is inconsistent with the feature type queried during training (typically: decimal vs double).
Before training, uniformly cast and store all feature tables as double.
score_batch throws Feature names unseen at fit time, or all samples have identical predicted values.
Preprocessing such as pd.get_dummies / StandardScaler was called directly outside the Pipeline during training and was not serialized into the model.
Use sklearn.Pipeline + ColumnTransformer + OneHotEncoder(handle_unknown="ignore") to pass the preprocessing steps and the model together as model to fe.log_model

Error Handling Recommendations

In production calls, it is recommended to catch different exception types separately to distinguish parameter errors from resource and TencentCloud API errors, and to retain the request_id for troubleshooting:
from tencentcloud.common.exception.tencent_cloud_sdk_exception import TencentCloudSDKException
from wedata.common.utils.env_utils import EnvironmentError as WedataEnvError

try:
    fe.publish_table(
        catalog_name="<offline_catalog_name>",
        schema_name="<offline_schema_name>",
        table_name="<offline_table_name>",
        online_db_name="<online_schema_name>",
        online_table_name="<online_table_name>",
    )
except ValueError as e:
    # Business parameter error: record it directly and return.
    logger.error("invalid params: %s", e)
except RuntimeError as e:
    # Resource / TencentCloud API errors: the request_id in the error message can be used to contact support.
    logger.error("publish failed: %s", e)
except TencentCloudSDKException as e:
    logger.error("cloud api error code=%s msg=%s reqid=%s",
                 e.get_code(), e.get_message(), e.get_request_id())
except WedataEnvError as e:
    logger.error("env not ready: %s", e)
Tip
If you encounter an API or exception scenario that is not covered in the documentation, submit a ticket in the ticket system and include the request_id, SDK version, and error stack for faster troubleshooting.

FAQs

Q: What Should I Do If score_batch Reports That feature_spec.yaml Cannot Be Found?

feature_spec.yaml is automatically written when fe.log_model is called. If the native mlflow.<flavor>.log_model is used during training instead of fe.log_model, the feature source information is not written. Use fe.log_model to log the model again.

Q: Why Does an Error Occur When a Model Is Published as an Online Service, Indicating That There Are Offline Feature Tables Not Published as Online Tables?

All offline feature tables referenced by the model artifact must be published as online feature tables before the online service can be created. Go back to the corresponding offline feature tables, complete the publishing, and wait for the synchronization task to succeed on its first run before retrying. For details, see page operations.

Q: Why Does Online Feature Data Seem to Lag Behind Offline Tables?

Data in online feature tables comes from synchronization tasks, and latency depends on the synchronization mode: Scheduled trigger is limited by the scheduling cycle, while continuous running offers the highest real-time performance but still has task execution intervals. If you have high real-time requirements, configure a smaller execution interval in continuous running mode and monitor the running status and latency of synchronization tasks.

References

Page operations
Feature Engineering SDK
Anterior: Feature Engineering SDKPróximo: What Is Model Management

Ajuda e Suporte

Esta página foi útil?

comentários

Search
    Enter keywords to search documentation