AI Assistant Configuration

Vector Library Service

Please contact the after-sales team to obtain the deployment script.

Script Deployment

The deployment package contains deploy.sh, Compose files, the release manifest, and offline resources. Configuration, models, and database data are stored separately from the deployment package. Do not run docker compose up directly; always use deploy.sh.

The package can be placed in any directory, for example:

/opt/vector-server-release/
├── deploy.sh
├── docker-compose.yaml
├── release.env
├── hsenv
└── artifacts/

The default runtime data directory is:

/var/lib/vector-server/
├── config/
│   └── .env
└── models/

PostgreSQL data is stored in the Docker volume for the vector-server Compose project. When upgrading the deployment package, do not delete /var/lib/vector-server/ or the PostgreSQL volume.

Initial Deployment

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 prints the actual connection information.

Offline Deployment

For offline environments, place images and models in the deployment package's artifacts/ directory:

artifacts/
├── vectorize-pg-<version>.tar
├── vector-serve-<version>.tar
└── models--intfloat--multilingual-e5-base.tar.gz

If Docker is not installed, also prepare offline Docker and Docker Compose installation packages. Enable offline mode before deployment:

cd /opt/vector-server-release
export OFFLINE_NETWORK=true
./deploy.sh -m check
./deploy.sh -m start

If an image or model is missing, the script reports the required file and exits without starting the service.

Configuration and Ports

The persistent configuration file is located at /var/lib/vector-server/config/.env. Common settings are:

COMPOSE_PROJECT_NAME=vector-server
VECTOR_SERVER_DATA_DIR=/var/lib/vector-server
VECTOR_SERVER_CONFIG_DIR=/var/lib/vector-server/config
MODEL_BASE_DIR=/var/lib/vector-server/models

VECTORIZE_PG_EXPOSE_PORT=54321
VECTOR_SERVE_EXPOSE_PORT=3000
VECTORIZE_POSTGRES_DEFAULT_CONTAINER_NAME="vector-server_vectorize-pg"
VECTOR_SERVE_API_DEFAULT_CONTAINER_NAME="vector-server_vector-serve-api"

To use a separate disk for runtime data, update the three directory settings, for example:

VECTOR_SERVER_DATA_DIR=/data/vector-server
VECTOR_SERVER_CONFIG_DIR=/data/vector-server/config
MODEL_BASE_DIR=/data/vector-server/models

In production, do not store configuration or models inside the deployment package. start and upgrade automatically check for container-name and port conflicts. If a conflict is found, the script generates an available name or selects an available port from 20000-59999, then writes it to the persistent configuration file. Use the actual ports recorded in the startup log and .env.

Upgrade and Migration

To upgrade a service already using the persistent data directory, use the new deployment package:

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

The upgrade preserves configuration, models, container names, ports, and the PostgreSQL volume. Do not run ./deploy.sh -m down before upgrading, and do not delete the runtime data directory or PostgreSQL volume.

If an earlier version stored .env and models in the old deployment directory, perform the initial migration with:

cd /opt/vector-server-release-new
./deploy.sh -m upgrade --legacy-dir /opt/vectorize-pg

--legacy-dir is only required for the initial migration; it is not needed for later upgrades.

Common Commands

# Check the environment
./deploy.sh -m check

# Prepare images, models, and configuration without starting the service
./deploy.sh -m prepare

# Initial or normal startup
./deploy.sh -m start

# Upgrade a deployed service
./deploy.sh -m upgrade

# Stop or restart the service while preserving data
./deploy.sh -m stop
./deploy.sh -m restart

# View status or the latest 100 log lines
./deploy.sh -m status
./deploy.sh -m logs

# Remove containers and networks; named volumes are preserved by default
./deploy.sh -m down

k8s Deployment

Deploy vector-serve and vector-postgres

kubectl -n [namespace] apply -f vectorize-pg.yaml -f vector-serve.yaml

Please Note

Before deployment, confirm the storage system used by the current cluster and modify the storage configuration in the vector-serve deployment file as needed. The default is longhorn.

Copy the model file (please contact support to obtain the download link)

kubectl -n [namespace] cp models--intfloat--multilingual-e5-base.tar.gz vector-serve-xxxx:/root/.cache/huggingface/hub/
kubectl -n [namespace] exec -t vector-serve-xxxx -- bash -c "cd /root/.cache/huggingface/hub && tar xf models--intfloat--multilingual-e5-base.tar.gz"

Modify HENGSHI Service Configuration (Requires Restarting HENGSHI Service)

Single-node Deployment
Edit the /opt/hengshi/conf/hengshi-sense-env.sh file
Uncomment the VECTOR_DB_URL and VECTOR_ENDPOINT variables.

export VECTOR_DB_URL="jdbc:postgresql://<SERVER_IP>:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8"
export VECTOR_ENDPOINT="http://<SERVER_IP>:3000/v1/embeddings"

Docker Deployment
Navigate to the deployment directory docker-compose-x.x, and use vi/vim to open the .env file and add the following parameters.

# VECTOR_DB
VECTOR_DB_URL=jdbc:postgresql://<SERVER_IP>:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8
VECTOR_ENDPOINT=http://<SERVER_IP>:3000/v1/embeddings

K8s Deployment
Edit the configmap named "hengshi-sense" in the namespace where HENGSHI is deployed, and add the following parameters.

VECTOR_DB_URL: "jdbc:postgresql://<SERVER_IP>:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8"
VECTOR_ENDPOINT: "http://<SERVER_IP>:3000/v1/embeddings"

Note:

Replace <SERVER_IP> with the IP address of the deployment machine, which can be obtained using the ifconfig command.

For K8s deployment, you can configure it as the address of a Service, such as vector-serve and vectorize-pg, or use the NodeIP+NodePort format for configuration.

Restart Operations

Standalone

# Please ensure the path is updated to the current deployment path of hengshi, default is /opt/hengshi
/opt/hengshi/bin/hengshi-sense-bin restart hengshi

Docker

# For Docker deployment, execute docker-compose down and then docker-compose up -d to apply the new configuration changes
cd docker-compose-x.x
docker-compose down
docker-compose up -d

K8s

# Replace [namespace] with the actual deployment namespace, and replicas with the actual number of pods deployed, default is 1
kubectl -n [namespace] scale deployment hengshi --replicas=0
kubectl -n [namespace] scale deployment hengshi --replicas=1

Common Errors

Script Deployment Fails to Start or the Service Is Unavailable

Run the following commands in the deployment package directory first:

./deploy.sh -m check
./deploy.sh -m status
./deploy.sh -m logs

Confirm that Docker, Compose, images, and models are ready. In an offline environment, ensure the image and model files in artifacts/ are complete and that OFFLINE_NETWORK=true is set. If the service configuration was changed because of a port or container-name conflict, obtain the actual port from /var/lib/vector-server/config/.env or the startup log, then update HENGSHI's VECTOR_DB_URL and VECTOR_ENDPOINT.

query vector db fail

This issue is usually caused by a communication failure between vector-serve and vector-postgres. You can use the following methods to confirm if everything is functioning properly:

• Confirm through the vector-serve interface request:

# Execute on the server where hengshi is located
# For docker/k8s deployment, enter the hengshi-sense container to execute
curl -X POST http://localhost:3000/v1/embeddings   -H 'Content-Type: application/json'   -d '{"input": [" abc"],"model": "intfloat/multilingual-e5-base"}'

# A normal response will return the following information:
{"data":[{"embedding":[-0.003002965124323964,0.03069210797548294,-0.002330577466636896,0.03642740473151207,0.019268367439508438,-0.007615369278937578,-0.03148505836725235,-0.012897394597530365,0.04027864709496498,0.039263855665922165,0.0038333579432219267,-0.02870958484709263,0.0900445431470871,-0.005433060694485903,-0.028027791529893875,-0.0381585918366909,0.013700217008590698,-0.03247552365064621,0.05149281769990921,0.006922998931258917,0.07466138899326324,-0.050848592072725296,0.037725191563367844,-0.025164397433400154,0.03877019137144089,-0.024159127846360207,0.023425891995429993,0.0228315070271492,-0.054315488785505295,0.05397752672433853,0.03425733000040054,-0.05478481948375702,0.03427012637257576"index":0}],"model":"intfloat/multilingual-e5-base"}

• Confirm through vector's query SQL:

# For docker deployment, enter the vector-postgres container
docker ps | grep "postgres-vectorize"
docker exec -it <container_id> bash

# Execute the psql command to enter the SQL console
psql (16.3 (Debian 16.3-1.pgdg120+1))
Type "help" for help.

postgres=# select vectorize.transform_embeddings(input => 'abc', model_name => 'intfloat/multilingual-e5-base')::TEXT;
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 {-0.003002965124323964,0.03069210797548294,-0.002330577466636896,0.03642740473151207,0.01926836743950844,-0.007615369278937578,-0.03148505836725235,-0.012897394597530363,0.04027864709496498,0.039263855665922165,0.0038333579432219263,-0.02870958484709263,0.0900445431470871,-0.005433060694485903,-0.028027791529893875,-0.0381585918366909,0.013700217008590698,-0.03247552365064621,0.05149281769990921,0.006922998931258917,0.07466138899326324,-0.050848592072725296,0.03772519156336784,-0.02516439743340015,0.03877019137144089,-0.024159127846360207,0.023425891995429993,0.0228315070271492,-0.054315488785505295,0.05397752672433853,0.03425733000040054,-0.05478481948375702,0.03427012637257576,0.018632836639881138,0.04853101447224617,0.00798027589917183,-0.00742304464802146,-0.03389187157154083,0.

# For k8s deployment, enter the vector-postgres container
kubectl -n [namespace] exec -it vectorize-pg-xxxx -- bash

# Execute the psql command to enter the SQL console
psql (16.3 (Debian 16.3-1.pgdg120+1))
Type "help" for help.

postgres=# select vectorize.transform_embeddings(input => 'abc', model_name => 'intfloat/multilingual-e5-base')::TEXT;
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
 {-0.003002965124323964,0.03069210797548294,-0.002330577466636896,0.03642740473151207,0.01926836743950844,-0.007615369278937578,-0.03148505836725235,-0.012897394597530363,0.04027864709496498,0.039263855665922165,0.0038333579432219263,-0.02870958484709263,0.0900445431470871,-0.005433060694485903,-0.028027791529893875,-0.0381585918366909,0.013700217008590698,-0.03247552365064621,0.05149281769990921,0.006922998931258917,0.07466138899326324,-0.050848592072725296,0.03772519156336784,-0.02516439743340015,0.03877019137144089,-0.024159127846360207,0.023425891995429993,0.0228315070271492,-0.054315488785505295,0.05397752672433853,0.03425733000040054,-0.05478481948375702,0.03427012637257576,0.018632836639881138,0.04853101447224617,0.00798027589917183,-0.00742304464802146,-0.03389187157154083,0.