From Semantic Preparation to Model Acceptance: RAG and Deployment Engineering for HENGSHI SENSE Data Agent

Abstract: The challenge in enterprise data questions is to produce verifiable results within defined data scopes, business definitions, and permission boundaries, rather than simply send a natural-language sentence to a large model. HENGSHI SENSE Data Agent organizes semantic preparation, vector retrieval, model calls, and data queries into an operable pipeline. Using the currently public 6.2 manuals as a configuration baseline and the public release notes for 6.3.2 and 6.2.5 as references, this article explains vector-service delivery and upgrades, RAG’s role in the pipeline, and how models, prompts, permissions, and acceptance should be implemented together. Actual deployment should follow the release notes, delivery package, and startup logs for the version in use.

1 Prepare data semantics and responsibility boundaries first

1.1 Data Agent must understand business objects before handling questions

Data Agent answer quality begins with data preparation. Datasets, fields, and atomic metrics need clear names, types, and descriptions; business terminology, synonyms, default filters, and statistical definitions belong in dataset knowledge management or appropriate prompts. For organization-specific terms such as “fiscal year,” “small order,” and “valid customer,” administrators should define time windows, filters, and corresponding metrics rather than leave interpretation to the model. Irrelevant fields can be hidden to keep them out of retrieval candidates and prompts, reducing ambiguity and context cost.

For complex definitions that need reuse, first preserve them as metrics in the data environment and maintain change records. The model then works with explainable business semantics rather than assembling calculation rules within a single conversation. Data Agent offers tuning locations for Agent core instructions, resource search instructions, value-set query instructions, HQL execution instructions, and industry and private-domain instructions. Prompts should specify roles, terminology, and boundaries and be reviewed by people familiar with the business; they are not a substitute for data governance.

Maintain tuning configurations as controlled business rules. Administrators can constrain preferred resources through resource search instructions, describe aliases for selectable values such as regions and product categories through value-set query instructions, and add default row counts or required filters through HQL execution instructions. Each rule should have an applicable scope, an owner, and a review date. Conflicting rules, overly long descriptions, and temporary exceptions turned into permanent constraints all make retrieval and execution harder to explain.

• Document common metrics’ definitions, granularity, time basis, units, and treatment of refunds, discounts, taxes, and other conditions.
• Maintain mappings between business aliases and fields or metrics in knowledge management to avoid selecting similarly named objects incorrectly.
• Preserve validated questions and analytical steps as examples, dashboards, or intelligent interpretation instructions, and review them after data or definition changes.
• Review, add, remove, and revise content produced through intelligent learning before using it in later questions.

1.2 RAG narrows candidates; permissions and fact checking still need their own controls

RAG connects a question with relevant datasets, fields, metrics, function descriptions, or examples, then provides a limited candidate context to the model. HENGSHI SENSE vector search can work with tokenized search and model-based selection; it narrows candidates but does not guarantee that selected candidates, generated queries, or final interpretations are correct. Similarity thresholds, field-count limits, example counts, and other parameters should be adjusted to the organization’s data scale and acceptance results; defaults are not universal accuracy promises.

Vector similarity does not determine permissions. Visible data scope, roles, and selected data sources should first constrain retrieval and query boundaries. A vector store preserves and retrieves semantic representations and related retrieval material; it neither serves as a permission system nor replaces backups of original data, metadata, and configuration. After knowledge changes, re-vectorize and recheck retrieval results. The fact that old vectors remain queryable does not establish that they describe current schemas or metric definitions.

2 Vector services: deploy through delivery scripts and operate according to runtime state

2.1 Manage the delivery package, runtime directory, and persistent state separately

The vector-service delivery package contains deploy.sh, Compose files, a release-version manifest, and offline resources. Official configuration instructions require management through deploy.sh, rather than running docker compose up directly. Configuration, models, and database data should be separate from the package: the default runtime directory contains configuration files and model directories, while PostgreSQL data resides in the Compose project’s Docker volume. Preserve the runtime directory and PostgreSQL volume before upgrading the delivery package; check first and then upgrade, without treating runtime-state deletion as routine maintenance.

cd /opt/vector-server-release
./deploy.sh -m check
./deploy.sh -m start

The startup script checks the environment, initializes configuration, prepares images and models, handles container-name and port conflicts, creates the vectorize extension, and reports actual connection information. Example default ports such as 3000 and 54321 are not fixed across all environments. On detecting conflicts, the script selects available ports and writes the result back to the fixed configuration file. HENGSHI SENSE VECTOR_DB_URL and VECTOR_ENDPOINT should use actual values from startup logs and the runtime directory’s .env; then restart services according to the current deployment method to apply the configuration.

Offline environments also require matching images and models in the delivery package’s artifacts/ directory, with offline mode set before checks and startup. Kubernetes deployments likewise need storage settings adapted to the cluster’s actual storage system. In every form, the deployment package is replaceable while the runtime directory and PostgreSQL volume are protected runtime state.

2.2 Default model, connectivity, and vector lifecycle

The bundled vector service currently uses intfloat/multilingual-e5-base as its default model configuration. This is a deployment baseline, not proof that every project uses one fixed model. Before replacing it, confirm vector-service support, model-file availability in the runtime environment, and whether existing vectors need rebuilding. Representations generated by different embedding models must not be assumed interchangeable or directly comparable. After replacement, sample retrieval for synonyms, easily confused fields, historical definitions, and permission scopes separately.

When troubleshooting, distinguish an unavailable vector service from poor question-answering results. For service availability, use the delivery script’s check, status, and logs in order to inspect the environment, images, models, containers, and actual ports. Next verify that the embedding endpoint returns vectors and use vectorize.transform_embeddings in the database to validate the extension-to-model chain. Do not broadly describe the implementation as one fixed vector index or extension combination; the delivery package and observed runtime state govern it.

select vectorize.transform_embeddings(
  input => '验收文本',
  model_name => 'intfloat/multilingual-e5-base'
)::text;

Poor answer quality usually requires starting with data assets. After publishing a data package, changing field or metric descriptions, changing definitions, or adjusting synonyms, rerun data vectorization and monitor progress in task management’s execution plans. Continuously updated assets can use scheduled tasks, but important changes should each retain a change record and human sampling. Vectorized outputs are rebuildable retrieval material; original data and required metadata backups still need separate management under the data platform’s backup policy.

3 Model integration: treat compatibility as an interface contract to validate

3.1 Validate endpoints, authentication, parameters, and runtime capabilities individually

Cloud and self-hosted models both need accessible HTTP service addresses; cloud services usually also require enterprises to obtain and safeguard their own API keys. The platform lists multiple model providers and provides an OpenAI-API-Compatible option. Interface compatibility means a service can be configured using agreed request and response formats, not that every service integrates without configuration or acceptance. Before integration, use “Test model connection” to confirm the endpoint, authentication, model name, and availability, then perform business acceptance using real questions.

Acceptance item	What to check	Passing evidence
Requests and authentication	Endpoint path, protocol, authentication method, key permissions, and model name	Connection tests and controlled requests return expected responses
Request parameters	temperature, max_tokens or max_completion_tokens, JSON output, and thinking parameters	Enable and disable relevant settings separately and retain request logs
Capability coordination	Tool calls, streaming, timeout, retry, and rate-limit behavior	Cases covering success, timeout, rate limiting, and unsupported formats
Data boundaries	Scope of prompts, metadata, and result summaries sent to external services	Security, procurement, and business stakeholders confirm and retain configuration

Self-hosted models can place model services and related runtime environments within an enterprise-controlled network. Once an external model endpoint is configured, data sent to it remains subject to the provider’s service, contracts, and regional settings. Both modes can coexist, but deploying a component locally does not automatically keep external model calls within the enterprise boundary. Keys should not appear in frontend scripts or logs, and calling services should use least privilege, access control, and auditing.

3.2 Workflow and Agent are different runtime services; API is an integration method

Before selecting a model, decide who continuously advances question answering. Workflow mode uses a backend workflow service to handle execution of a question, fitting scenarios that centralize execution logic, permission boundaries, and stable delivery in the backend. Agent mode retains continuous progression, state changes, tool calls, and incremental feedback. Browser embedding uses frontend embedding capabilities, while backend Agent mode requires the corresponding Node.js Agent service. iframe, JS SDK, and API are integration methods and should not be confused with runtime modes.

Runtime mode	Private-deployment candidates in the public manuals	Selection and acceptance focus
Workflow	Qwen3.5-27B	Structured tasks, instruction following, timeout, and result stability
Agent	Kimi-K2.5, MiniMax-M2.5, DeepSeek-V4-Flash, GLM-5	Multi-step reasoning, tool calls, long conversations, termination without progress, and resource limits

These names are candidates in the current manuals, not a universal ranking, and do not replace vendors’ requirements for hardware, quantization, licensing, and serving frameworks. Output speed and quality depend jointly on hardware, model size, input/output length, optimization techniques, and the system environment. Validate business questions, tool calls, and concurrency boundaries on controlled datasets before choosing a production configuration.

4 Validate each question-answering layer: semantics, retrieval, HQL, and results

4.1 A verifiable path from natural language to data results

A data question typically passes through scope and permission constraints, resource and example retrieval, context assembly, model planning, query-expression generation, data execution, and result presentation. RAG serves candidate retrieval and context preparation within that chain. For HENGSHI data questions, HQL is the product semantic layer’s query language or query expression, not generic SQL that can be sent directly to arbitrary physical databases. Actual query processing depends on data-source connections, semantic models, execution engines, and configuration. Acceptance should check agreement among semantics, execution results, and permissions, rather than merely inspect plausible generated text.

In real projects, a model may first select fields, metrics, relevant functions, and examples, then form HQL-related query intent or expressions. What the physical data source ultimately executes still depends on connectors and query engines. When investigating incorrect results, therefore check separately what the model selected, what HQL expressed, how the platform executed that expression, and what the data source returned. Mixing logs from these four layers obscures the actual failure point.

• Validate semantic preparation and retrieval candidates with questions involving synonyms, business aliases, date definitions, and metric definitions.
• Then validate scope and permissions with cross-dataset questions, empty results, requests outside visible scope, and hidden fields.
• Use manually known answers to check HQL dimensions, filters, aggregations, and time windows, and verify returned data.
• Finally check that charts, tables, and summaries faithfully reflect query results. Intelligent interpretation provides queries, summaries, and descriptions based on existing and historical data, not future predictions.

Acceptance questions and expected results can form a small regression set. For example, “Compare published metrics for two regions using the defined fiscal year” checks fiscal-year interpretation, regional filters, metric selection, and result verification together, turning acceptance standards into specific business tasks. Rerun this set after model upgrades, prompt adjustments, embedding-model replacement, or important data-asset changes; record differences, acceptance criteria, and conclusions.

4.2 Troubleshoot by failure layer and retain execution logs and boundary conditions

Failure layer	Priority checks	Evidence to retain
Data semantics	Updates to fields, metrics, knowledge management, prompts, and vectorization tasks	Change records, vectorization status, and manual retrieval samples
Vector service	Delivery-script status, actual ports, images, models, extensions, and connection information	check/status/logs output and connectivity results
Model calls	Endpoint, key, model name, parameters, timeout, streaming, and tool support	Connection tests, de-identified requests/responses, and provider error codes
Queries and permissions	Current role, question scope, HQL semantics, and data-source execution errors	Execution logs, role and scope, and reproducible questions
Presentation and summaries	Returned data, chart rendering, summarization, and browser network requests	Execution logs, Fetch/XHR responses, and system-debug exports

Data Agent and ChatBI conversation cards can copy full execution logs. When reproducing a problem, also retain Fetch/XHR responses from browser developer tools and enable real-time system debugging before exporting logs. A report should include the question text, user role, specified data scope, occurrence time, deployed version, actual endpoint status, and expected-versus-actual differences. De-identify keys, tokens, and sensitive original data. These records turn “the answer is wrong” into an engineering problem that can be located.

Public release notes show that 6.3.2, released September 23, 2026, includes a fix for ChatBI metric questions in dynamic business domains returning no results. The 6.2.5 maintenance release on the same date also fixes multi-turn data-source inheritance, questions failing to converge, and inconsistencies between summaries and chart data. Check the release notes for the actual running build before implementation. Version 6.2 manual pages are configuration references and should not be presented as the latest version for all environments.

5 Conclusion

Reliable data questions depend on checkable engineering constraints: govern data semantics first, let RAG narrow candidates, determine visible scope through permissions, preserve vector-service runtime state through delivery scripts, treat each model integration as interface and capability acceptance, and verify HQL, data execution, and result interpretation separately. These practices make models replaceable, data updatable, and problems reproducible, helping teams assess whether each configuration remains suitable as versions evolve.