RAG service API - - Alibaba Cloud Documentation Center

Limitations

This document applies only to RAG services deployed using image versions earlier than v0.3.0.

Go to the Elastic Algorithm Service (EAS) page and click the RAG service name. On the Overview page, find the image version in the Environment Information section.

Service access address and token

To call a RAG service, you need to get the service access address and token:

Log on to the PAI console. Select a region on the top of the page. Then, select the desired workspace and click Elastic Algorithm Service (EAS).
Click the name of the target service. In the Basic Information section, click View Endpoint Information.
In the Invocation Method dialog box, get the service access address (EAS_SERVICE_URL) and token (EAS_Token).
Important
- Remove the trailing slash (/) from the EAS_SERVICE_URL.
- To call the service using a public endpoint, the client must have internet access.
- To call the service using a VPC endpoint, the client must be in the same virtual private cloud (VPC) as the RAG service.

Chat API

This service provides an OpenAI-compatible API. To use specific features, configure the required settings on the RAG service WebUI.

Supported features

search_web: Enables web search. You must configure web search parameters.
chat_knowledgebase: Enables knowledge base queries. You must upload knowledge base files.
chat_llm: Uses only a large language model (LLM) to provide answers. You must configure LLM services.
chat_agent: Calls agent tools. You must configure agent-related code on the WebUI page.
chat_db: Queries a database or table. You must configure chat_db-related parameters on the WebUI page.

Request details
URL	`{EAS_SERVICE_URL}/v1/chat/completions`
Request method	POST
Request header	`Authorization: EAS_TOKEN` (Token for Elastic Algorithm Service (EAS))
Sample HTTP body	{ "model": "default", # The model name. Set this to default. "messages": [ {"role": "user", "content": "Hello"}, {"role": "assistant", "content": "Hello, how can I help you?"}, {"role": "user", "content": "What is the capital of Zhejiang Province?"}, {"role": "assistant", "content": "Hangzhou is the capital of Zhejiang Province."}, {"role": "user", "content": "What are some fun places to visit?"}, ], "stream": true, # Specifies whether to enable streaming output. "chat_knowledgebase": true, # Specifies whether to query the local knowledge base. "search_web": false, # Specifies whether to perform a web search. "chat_llm": false, # Specifies whether to use only LLM chat. "chat_agent": false, # Specifies whether to use an agent. "chat_db": false, # Specifies whether to perform a database query. "index_name": "default_index", # The index name for RAG scenarios. You can specify only one. If omitted, the default index is used. "max_tokens": 1024, # The maximum number of tokens to generate in the response. Example: 1024. "temperature": 0.1, # Controls the randomness of the generated content. Valid values: [0, 1]. A lower value indicates higher determinism, and a higher value indicates more diverse content. } Important When multiple features are enabled, the system evaluates them in the following priority order: `search_web`, `chat_knowledgebase`, `chat_agent`, `chat_db`, and `chat_llm`. For each request, the system uses intent recognition to determine whether to invoke a feature or respond directly using the LLM. If all feature parameters are `false` or omitted, the system defaults to a knowledge base query (`"chat_knowledgebase": true`).

Request examples

Web search

from openai import OpenAI
##### API configuration #####
# Replace <EAS_TOKEN> with your service token and <EAS_SERVICE_URL> with the service URL.
openai_api_key = "<EAS_TOKEN>"
openai_api_base = "<EAS_SERVICE_URL>/v1"
client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)
#### Chat ######
def chat():
    stream = True
    chat_completion = client.chat.completions.create(
        model="default",
        stream=stream,
        messages=[
            {"role": "user", "content": "Hello"},
            {"role": "assistant", "content": "Hello, how can I help you?"},
            {"role": "user", "content": "What is the capital of Zhejiang Province?"},
            {"role": "assistant", "content": "Hangzhou is the capital of Zhejiang Province."},
            {"role": "user", "content": "What are some fun places to visit?"},
        ],
        extra_body={
            "search_web": True,
        },
    )
    if stream:
        for chunk in chat_completion:
            print(chunk.choices[0].delta.content, end="")
    else:
        result = chat_completion.choices[0].message.content
        print(result)
chat()

Database query

from openai import OpenAI
##### API configuration #####
# Replace <EAS_TOKEN> with your service token and <EAS_SERVICE_URL> with the service URL.
openai_api_key = "<EAS_TOKEN>"
openai_api_base = "<EAS_SERVICE_URL>/v1"
client = OpenAI(
    api_key=openai_api_key,
    base_url=openai_api_base,
)
#### Chat ######
def chat():
    stream = True
    chat_completion = client.chat.completions.create(
        model="default",
        stream=stream,
        messages=[
            {"role": "user", "content": "How many cats are there?"},
            {"role": "assistant", "content": "There are 2 cats."},
            {"role": "user", "content": "What about dogs?"},
        ],
        extra_body={
            "chat_db": True,
        },
    )
    if stream:
        for chunk in chat_completion:
            print(chunk.choices[0].delta.content, end="")
    else:
        result = chat_completion.choices[0].message.content
        print(result)
chat()

Management API

Upload knowledge base files

Method
URL	`{EAS_SERVICE_URL}/api/v1/upload_data`
Request method	POST
Request header	`Authorization: EAS_TOKEN` # Your EAS service token. `Content-Type: multipart/form-data`
Request parameter	files: The files to upload. oss_path: The path in Object Storage Service (OSS). index_name: The index name. Defaults to `default_index`.

cURL request example

Upload a single file

 # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
 # Replace the path after "-F 'files=@" with your file path. 
 # Set index_name to your knowledge base index name. 
   curl -X 'POST' <EAS_SERVICE_URL>/api/v1/upload_data \
  -H 'Authorization: <EAS_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@example_data/paul_graham/paul_graham_essay.txt' \
  -F 'index_name=default_index'

To upload multiple files, use a -F 'files=@path' parameter for each file, as shown in the example below:

  # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
  # Replace the path after "-F 'files=@" with your file path. 
  # Set index_name to your knowledge base index name. 
  curl -X 'POST' <EAS_SERVICE_URL>/api/v1/upload_data \
  -H 'Authorization: <EAS_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'files=@example_data/paul_graham/paul_graham_essay.txt' \
  -F 'files=@example_data/another_file1.md' \
  -F 'files=@example_data/another_file2.pdf' \
  -F 'index_name=default_index'

Response example

  { "task_id": "2c1e557733764fdb9fefa0635389****" }

Check upload task status

Method
URL	`{EAS_SERVICE_URL}/api/v1/get_upload_state`
Request method	GET
Request header	`Authorization: EAS_TOKEN` # Your EAS service token.

cURL request example

# Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
# Set task_id to the ID returned by the file upload request. 
curl -X 'GET' '<EAS_SERVICE_URL>/api/v1/get_upload_state?task_id=2c1e557733764fdb9fefa0635389****' -H 'Authorization: <EAS_TOKEN>'

Response example

  {
    "task_id": "2c1e557733764fdb9fefa0635389****",
    "status": "completed",
    "detail": null
  }

Search the knowledge base

Method
URL	`{EAS_SERVICE_URL}/api/v1/query/retrieval`
Request method	POST
Request header	`Authorization: EAS_TOKEN` # Your EAS service token. `Content-Type: application/json`
Request parameter	question: The user's query. index_name: The index name. Defaults to `default_index`.

cURL request example

# Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
# Set question to the user's query. 
# Set index_name to your knowledge base index name. 
  curl -X 'POST' '<EAS_SERVICE_URL>/api/v1/query/retrieval' \
  -H 'Authorization: <EAS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
      "question": "What can I do when the x13-auto-arima component reports an error?",
      "index_name": "default_index"
  }'

Response example

{
  "docs": [
    {
      "text": "2.PAl-Studio/Designer FAQ 2.1. FAQ about algorithm components : \nCharacters that cannot be transcoded are displayed as \"blob.\" Ignore this error, because nodes in the downstream can read and process the data.\nWhat can I do when the x13-auto-arima component reports an error?\nMake sure that up to 1,200 training data samples are imported into the x13-auto-arima component.\nWhat can I do when the Doc2Vec component reports the CallExecutorToParseTaskFail error?",
      "score": 0.83608,
      "metadata": {
        "file_path": "***/pai_document.md",
        "file_name": "pai_document.md",
        "file_size": 3794,
        "creation_date": "2025-03-20",
        "last_modified_date": "2025-03-20"
      },
      "image_url": null
    }
  ]
}

Upload a datasheet for Chat_DB

Method
URL	`{EAS_SERVICE_URL}/api/v1/upload_datasheet`
Request method	POST
Request header	`Authorization: EAS_TOKEN` # Your EAS service token. `Content-Type: multipart/form-data`
Request parameter	file: The Excel or CSV file to upload.

cURL request example

  # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
  # Replace the path after "-F 'file=@" with your file path. 
  curl -X 'POST' <EAS_SERVICE_URL>/api/v1/upload_datasheet \
  -H 'Authorization: <EAS_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@example_data/titanic_train.csv'

Response example

  {
    "task_id": "3b12cf5fabee4a99a32895d2f693****",
    "destination_path": "./localdata/data_analysis/titanic_train.csv",
    "data_preview": "xxx"
  }

Upload Q and A pairs for Chat_DB

Method
URL	`{EAS_SERVICE_URL}/api/v1/upload_db_history`
Request method	POST
Request header	`Authorization: EAS_TOKEN` # Your EAS service token. `Content-Type: multipart/form-data`
Request parameter	file: The JSON file containing Q&A pairs. db_name: The database name.

cURL request example

  # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
  # Replace the path after "-F 'file=@" with your JSON file path. 
  # Set db_name to your database name. 
  curl -X 'POST' <EAS_SERVICE_URL>/api/v1/upload_db_history \
  -H 'Authorization: <EAS_TOKEN>' \
  -H 'Content-Type: multipart/form-data' \
  -F 'file=@example_data/db_query_history.json' \
  -F 'db_name=my_pets'

Response example

  {
    "task_id": "204191f946384a54a48b13ec00fd****",
    "destination_path": "./localdata/data_analysis/nl2sql/history/my_pets_db_query_history.json"
  }

Load database information

Method
URL	`{EAS_SERVICE_URL}/api/v1/query/load_db_info`
Request method	POST
Request header	`Authorization: EAS_TOKEN` # Your EAS service token.

cURL request example

# Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
curl -X 'POST' <EAS_SERVICE_URL>/api/v1/query/load_db_info -H 'Authorization: <EAS_TOKEN>'

Response example

"Load database info successfully."

Get knowledge base indexes

Method
URL	`{EAS_SERVICE_URL}/api/v1/indexes`
Request method	GET
Request header	`Authorization: EAS_TOKEN` # Specifies the service token for EAS.

cURL request example

# Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
curl -X 'GET' '<EAS_SERVICE_URL>/api/v1/indexes' -H 'Authorization: <EAS_TOKEN>'

Response example

  {
    "indexes": {
      "default_index": {
        "index_name": "default_index",
        "vector_store_config": {
          "persist_path": "localdata/storage",
          "type": "faiss",
          "is_image_store": false
        },
        "embedding_config": {
          "source": "huggingface",
          "model": "bge-m3",
          "embed_batch_size": 10,
          "enable_sparse": false
        }
      }
    },
    "current_index_name": "default_index"
  }

Create knowledge base index

Method
URL	`{EAS_SERVICE_URL}/api/v1/indexes/{index_name}`
Request method	POST
Request header	Authorization: EAS_TOKEN # Specifies the service token for EAS. Content-Type: application/json
Request parameters	index_name: The index name. vector_store_config: The vector database configuration. embedding_config: The embedding model configuration.

cURL request example

    # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
    # Replace <my_index> with the name for your new knowledge base index. 
    # Configure vector_store_config with your vector database settings.
    curl -X 'POST' '<EAS_SERVICE_URL>/api/v1/indexes/<my_index>' \
    -H 'Authorization: <EAS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
        "index_name": "<my_index>",
        "vector_store_config": {
            "type": "faiss"
        },
        "embedding_config": {
            "model": "bge-m3",
            "source": "huggingface"
        }
    }'

The preceding code uses Faiss as an example for the vector_store_config. Configurations for other vector databases are as follows:

Milvus

"vector_store_config":
      {
          "type":"milvus",
          "host":"c-xxxxx.milvus.aliyuncs.com",
          "port":19530,
          "user":"root",
          "password":"xxx",
          "database":"default",
          "collection_name":"test",
          "reranker_weights":[0.5,0.5]
      }

Hologres

"vector_store_config":
      {
          "type":"hologres",
          "host":"xxx",
          "port":xxx,
          "user":"xxx",
          "password":"xxx",
          "database":"default",
          "table_name":"test",
          "pre_delete_table":"false"
      }

Elasticsearch

"vector_store_config":
      {
          "type":"elasticsearch",
          "es_url":"xxx",
          "es_user":xxx,
          "es_password":"xxx",
          "es_index":"xxx"
      }

OpenSearch

"vector_store_config":
      {
          "type":"opensearch",
          "endpoint":"xxx",
          "instance_id":xxx,
          "username":"xxx",
          "password":"xxx",
          "table_name":"xxx"
      }

AnalyticDB

"vector_store_config":
      {
          "type":"analyticdb",
          "ak":"xxx",
          "sk":xxx,
          "region_id":"xxx",
          "instance_id":"xxx",
          "account":"xxx",
          "account_password":"xxx",
          "namespace":"xxx",
          "collection":"xxx"
      }

Tablestore

"vector_store_config":
      {
          "type":"tablestore",
          "endpoint":"xxx",
          "instance_name":xxx,
          "access_key_id":"xxx",
          "access_key_secret":"xxx",
          "table_name":"xxx"
      }

DashVector

"vector_store_config":
      {
          "type":"dashvector",
          "endpoint":"xxx",
          "api_key":xxx,
          "collection_name":"xxx",
          "partition_name":"xxx"
      }

Response example

  { "msg": "Add index 'my_index' successfully." }

Update knowledge base index

Method
URL	`{EAS_SERVICE_URL}/api/v1/indexes/{index_name}`
Request method	PATCH
Request header	`Authorization: EAS_TOKEN` # Specifies the service token for EAS. `Content-Type: application/json`
Request parameters	index_name: The index name. vector_store_config: The vector database configuration. embedding_config: The embedding model configuration.

cURL request example

    # Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
    # Replace <my_index> with the knowledge base index to update. 
    # Configure vector_store_config with the updated vector database settings.
    curl -X 'PATCH' '<EAS_SERVICE_URL>/api/v1/indexes/<my_index>' \
    -H 'Authorization: <EAS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
        "index_name": "<my_index>",
        "vector_store_config": {
            "type": "faiss"
        },
        "embedding_config": {
            "model": "bge-m3",
            "source": "huggingface"
        }
    }'

The vector_store_config in the preceding code uses Faiss as an example. For configuration examples for other vector databases, see the Create knowledge base index section.

Response example

  { "msg": "Update index 'my_index' successfully." }

Delete knowledge base index

Method
URL	`{EAS_SERVICE_URL}/api/v1/indexes/{index_name}`
Request method	DELETE
Request header	`Authorization: EAS_TOKEN` # Specifies the service token for EAS. `Content-Type: application/json`
Request parameters	index_name: The index name.

cURL request example

# Replace <EAS_TOKEN> and <EAS_SERVICE_URL> with your service token and service URL.
# Replace <my_index> with the knowledge base index to delete. 
curl -X 'DELETE' '<EAS_SERVICE_URL>/api/v1/indexes/<my_index>' -H 'Authorization: <EAS_TOKEN>' -H 'Content-Type: application/json' -d '{"index_name":"<my_index>"}'

Response example

  { "msg": "Delete index 'my_index' successfully." }

Get RAG configuration

Method
URL	`{EAS_SERVICE_URL}/api/v1/config`
Request method	GET
Request header	`Authorization: EAS_TOKEN` # Your EAS service token.

cURL request example (click to view details)

# Replace <EAS_TOKEN> with your service token and <EAS_SERVICE_URL> with your service URL.
curl -X 'GET' '<EAS_SERVICE_URL>/api/v1/config' -H 'Authorization: <EAS_TOKEN>'

Response example (click to view details)

  {
    "system": {
      "default_web_search": false,
      "query_type": "websearch"
    },
    "data_reader": {
      "concat_csv_rows": false,
      "enable_mandatory_ocr": false,
      "format_sheet_data_to_json": false,
      "sheet_column_filters": null,
      "number_workers": 4
    },
    "node_parser": {
      "type": "Sentence",
      "chunk_size": 500,
      "chunk_overlap": 10,
      "enable_multimodal": true,
      "paragraph_separator": "\n\n\n",
      "sentence_window_size": 3,
      "sentence_chunk_overlap": 200,
      "breakpoint_percentile_threshold": 95,
      "buffer_size": 1
    },
    "index": {
      "vector_store": {
        "persist_path": "localdata/storage",
        "type": "faiss",
        "is_image_store": false
      },
      "enable_multimodal": true,
      "persist_path": "localdata/storage"
    },
    "embedding": {
      "source": "huggingface",
      "model": "bge-m3",
      "embed_batch_size": 10,
      "enable_sparse": false
    },
    "multimodal_embedding": {
      "source": "cnclip",
      "model": "ViT-L-14",
      "embed_batch_size": 10,
      "enable_sparse": false
    },
    "llm": {
      "source": "openai_compatible",
      "temperature": 0.1,
      "system_prompt": null,
      "max_tokens": 4000,
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-xxx",
      "model": "qwen-max"
    },
    "multimodal_llm": {
      "source": "openai_compatible",
      "temperature": 0.1,
      "system_prompt": null,
      "max_tokens": 4000,
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-xxx",
      "model": ""
    },
    "functioncalling_llm": null,
    "agent": {
      "system_prompt": "You are a travel assistant, xxx",
      "python_scripts": "xxx",
      "function_definition": "xxx",
      "api_definition": "xxx"
    },
    "chat_store": {
      "type": "local",
      "persist_path": "localdata/storage"
    },
    "data_analysis": {
      "type": "mysql",
      "nl2sql_prompt": "Given an input question, xxx",
      "synthesizer_prompt": "Given an input question, xxx",
      "database": "my_pets",
      "tables": [],
      "descriptions": {},
      "enable_enhanced_description": false,
      "enable_db_history": true,
      "enable_db_embedding": true,
      "max_col_num": 100,
      "max_val_num": 1000,
      "enable_query_preprocessor": true,
      "enable_db_preretriever": true,
      "enable_db_selector": true,
      "user": "root",
      "password": "xxx",
      "host": "127.0.0.1",
      "port": 3306
    },
    "intent": {
      "descriptions": {
        "rag": "\nThis tool can help you get more specific information from the knowledge base.\n",
        "tool": "\nThis tool can help you get travel information about time, weather, flights, train and hotels.\n"
      }
    },
    "node_enhancement": {
      "tree_depth": 3,
      "max_clusters": 52,
      "proba_threshold": 0.1
    },
    "oss_store": {
      "bucket": "",
      "endpoint": "oss-cn-hangzhou.aliyuncs.com",
      "ak": null,
      "sk": null
    },
    "postprocessor": {
      "reranker_type": "no-reranker",
      "similarity_threshold": 0.5
    },
    "retriever": {
      "vector_store_query_mode": "default",
      "similarity_top_k": 3,
      "image_similarity_top_k": 2,
      "search_image": false,
      "hybrid_fusion_weights": [0.7, 0.3]
    },
    "search": {
      "source": "google",
      "search_count": 10,
      "serpapi_key": "142xxx",
      "search_lang": "zh-CN"
    },
    "synthesizer": {
      "use_multimodal_llm": false,
      "system_role_template": "You are xxx",
      "custom_prompt_template": "Your goal is to provide accurate, useful, and easy-to-understand information. xxx"
    },
    "query_rewrite": {
      "enabled": true,
      "rewrite_prompt_template": "# Role\nYou are a professional information retrieval expert, xxx",
      "llm": {
        "source": "openai_compatible",
        "temperature": 0.1,
        "system_prompt": null,
        "max_tokens": 4000,
        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api_key": null,
        "model": ""
      }
    },
    "guardrail": {
      "endpoint": null,
      "region": null,
      "access_key_id": null,
      "access_key_secret": null,
      "custom_advice": null
    }
  }

Update RAG configuration

Method
URL	`{EAS_SERVICE_URL}/api/v1/config`
Request method	PATCH
Request header	`Authorization: EAS_TOKEN` # Your EAS service token. `Content-Type: application/json`
Request parameter	new_config: The configuration properties to update.

cURL request example (click to view details)

    # Replace <EAS_TOKEN> with your service token and <EAS_SERVICE_URL> with your service URL.
    curl -X 'PATCH' '<EAS_SERVICE_URL>/api/v1/config' \
    -H 'Authorization: <EAS_TOKEN>' \
    -H 'Content-Type: application/json' \
    -d '{
        "system": {
          "default_web_search": false,
          "query_type": "websearch"
        },
        "data_reader": {
          "concat_csv_rows": false,
          "enable_mandatory_ocr": false,
          "format_sheet_data_to_json": false,
          "sheet_column_filters": null,
          "number_workers": 4
        },
        "node_parser": {
          "type": "Sentence",
          "chunk_size": 500,
          "chunk_overlap": 10,
          "enable_multimodal": true,
          "paragraph_separator": "\n\n\n",
          "sentence_window_size": 3,
          "sentence_chunk_overlap": 200,
          "breakpoint_percentile_threshold": 95,
          "buffer_size": 1
        },
        ...
    }' # For more configuration details, see the response example for "Get RAG service configuration".

Response example (click to view details)

  { "msg": "RAG configuration updated successfully." }