--- url: /v6.2/en-us/ai-config.md --- # 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: ```text /opt/vector-server-release/ ├── deploy.sh ├── docker-compose.yaml ├── release.env ├── hsenv └── artifacts/ ``` The default runtime data directory is: ```text /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 ```bash 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: ```text artifacts/ ├── vectorize-pg-.tar ├── vector-serve-.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: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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 ```bash # 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` ```shell kubectl -n [namespace] apply -f vectorize-pg.yaml -f vector-serve.yaml ``` > \[!CAUTION] 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) ```shell 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. ```bash export VECTOR_DB_URL="jdbc:postgresql://:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8" export VECTOR_ENDPOINT="http://: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. ```bash # VECTOR_DB VECTOR_DB_URL=jdbc:postgresql://:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8 VECTOR_ENDPOINT=http://:3000/v1/embeddings ``` K8s Deployment Edit the `configmap` named "hengshi-sense" in the namespace where HENGSHI is deployed, and add the following parameters. ```yaml VECTOR_DB_URL: "jdbc:postgresql://:54321/postgres?user=postgres&password=postgres&useUnicode=true&characterEncoding=utf8" VECTOR_ENDPOINT: "http://:3000/v1/embeddings" ``` > \[!CAUTION] Note: > Replace `` 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 ```bash # 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 ```bash # 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 ```bash # 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: ```bash ./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: ```shell # 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: ```shell # For docker deployment, enter the vector-postgres container docker ps | grep "postgres-vectorize" docker exec -it 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. ``` ```shell # 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. ```