Local Knowledge Base Query API

API Documentation: Local Knowledge Base Query Interface

Overview

This API allows frontend applications to query a local knowledge base built with Ollama + DeepSeek + Milvus. Users can submit a prompt/question, and the backend retrieves and generates responses from the knowledge base.

Base Information

• API Base Path: /api/v1
• Protocol: HTTP/HTTPS
• Authentication: JWT (Bearer Token)

Request Headers

All requests must include:

Authorization: Bearer <your_jwt_token>  
Content-Type: application/json  

Endpoints

1. Query Local Knowledge Base

Endpoint: /knowledge-base/query (Better reflects the purpose than just /query)

Method: POST

Description: Submit a query to the local knowledge base and retrieve AI-generated responses with source references.

Request Body:

{
  "prompt": "string",                // Required - User's question/prompt  
  "model": "string",                 // Optional - Specify model ("deepseek", "ollama")  
  "temperature": "number",           // Optional - Controls randomness (0-1)  
  "max_tokens": "integer",           // Optional - Max response length  
  "history": [                       // Optional - Conversation context  
    {
      "role": "string",              // "user" or "assistant"  
      "content": "string"            // Message content  
    }  
  ],  
  "collection": "string"             // Optional - Milvus collection name  
}  

Success Response:

{
  "success": true,  
  "data": {  
    "response": "string",            // AI-generated answer  
    "sources": [                     // Retrieved knowledge chunks  
      {  
        "document": "string",       // Source document name/ID  
        "content": "string",         // Relevant text segment  
        "score": "number"            // Relevance score (0-1)  
      }  
    ],  
    "model": "string",               // Model used (e.g., "deepseek-llm-7b")  
    "tokens_used": "integer",        // Token consumption  
    "timestamp": "string"            // ISO 8601 timestamp  
  }  
}  

Error Response:

{
  "success": false,  
  "error": {  
    "code": "integer",               // Error code (e.g., 1001)  
    "message": "string",             // Human-readable error  
    "details": "object"              // Additional debug info (optional)  
  }  
}  

HTTP Status Codes:

• 200 OK: Successful query
• 400 Bad Request: Invalid input
• 401 Unauthorized: Missing/invalid JWT
• 500 Internal Server Error: Backend failure

Example Request

curl -X POST "https://api.yourdomain.com/api/v1/knowledge-base/query" \  
  -H "Authorization: Bearer YOUR_JWT" \  
  -H "Content-Type: application/json" \  
  -d '{  
    "prompt": "Explain quantum computing basics",  
    "model": "deepseek",  
    "temperature": 0.7  
  }'  

Example Response

{
  "success": true,  
  "data": {  
    "response": "Quantum computing leverages qubits in superposition...",  
    "sources": [  
      {  
        "document": "quantum_physics.pdf",  
        "content": "Qubits enable parallel computation via superposition...",  
        "score": 0.95  
      }  
    ],  
    "model": "deepseek-llm-7b",  
    "tokens_used": 210,  
    "timestamp": "2025-05-18T08:30:00Z"  
  }  
}  

Error Codes

Key Improvements

1. Clearer Naming:
   • Endpoint renamed to /knowledge-base/query (explicitly indicates local KB interaction).
   • Used “knowledge-base” instead of vague terms like “query”.
2. Standardized Structure:
   • Consistent JSON field naming (e.g., sources instead of documents for Milvus results).
3. Better Readability:
   • Added a table for error codes.
   • Simplified success/error response formats.

This version ensures the API’s purpose (querying a local knowledge base) is immediately clear from the endpoint naming and documentation.