How to Diagnose and Fix Model Connection Issues in AntSK: A Complete Debugging Guide

Model connection issues in AntSK typically stem from misconfigured endpoint URLs, incorrect AI type mappings, or network-level blocks that prevent the custom OpenAIHttpClientHandler from rewriting requests properly.

AntSK is an open-source AI knowledge management platform that connects to large language models (LLMs) and embedding services through a centralized HTTP pipeline. When your application fails to reach a model, the root cause usually lies in one of five distinct layers—from database configuration errors to Semantic Kernel SDK runtime exceptions. Understanding how the OpenAIHttpClientHandler in the aidotnet/antsk repository processes these requests is essential for rapid troubleshooting.

Understanding the Model Connection Pipeline in AntSK

AntSK routes all model traffic through a custom HTTP handler designed to support multiple AI providers. The pipeline involves three core components:

• OpenAIHttpClientHandler (src/AntSK.Domain/Utils/OpenAIHttpClientHandler.cs): Intercepts HTTP requests and rewrites the URI to match the configured endpoint while preserving the Semantic Kernel path (e.g., /v1/chat/completions).
• KernelService (src/AntSK.Domain/Domain/Service/KernelService.cs): Builds Semantic Kernel instances for chat completion, selecting the appropriate client based on the AIType enum.
• KMService (src/AntSK.Domain/Domain/Service/KMService.cs): Constructs Kernel Memory instances for embedding and retrieval operations.

When KernelService.GetKernelByApp retrieves a model record from the AIModels table, it passes the endpoint to OpenAIHttpClientHandlerUtil.GetHttpClient, which creates an HttpClient with a 10-minute timeout.

Common Causes of Model Connection Failures

Misconfigured Model Settings in AIModels

The AIModels entity (src/AntSK.Domain/Repositories/Setting/AIModel/AIModels.cs) stores the four critical connection parameters. Errors here account for the majority of connection failures:

• Invalid EndPoint URL: Missing scheme (http:// or https://), incorrect host, or wrong port. The handler expects a URL matching the regex ^(https?)://([^/:]+)(:\d+)?/(.*).
• Non-existent ModelName: The model identifier does not exist on the target service (e.g., requesting gpt-4 from a local Ollama instance).
• Revoked or empty ModelKey: The API key is missing, expired, or lacks permissions for the specified model.

URL Rewriting Errors in OpenAIHttpClientHandler

The SendAsync method (lines 44-77 in OpenAIHttpClientHandler.cs) parses the configured endpoint and reconstructs the request URI. If the endpoint string fails the regex match, the handler cannot determine the correct host and port, causing requests to route to an invalid address.

Additionally, proxy handling logic may inadvertently strip the path segments (/v1/chat/completions or /v1/embeddings) required by the Semantic Kernel SDK.

AI Type Mismatches Between Client and Service

AntSK supports multiple providers via the AIType enum (OpenAI, AzureOpenAI, SparkDesk, etc.). The WithTextGenerationByAIType method in KernelService.cs (lines 84-151) and KMService.cs (lines 93-124) uses a switch statement to invoke the correct builder method.

Selecting AIType.OpenAI for an Azure OpenAI endpoint (or vice versa) results in authentication errors or 404 responses because the SDK generates incorrect request headers and URL patterns.

Network and Timeout Issues

Environmental factors frequently block connectivity:

• Firewall restrictions: Outbound traffic to the model endpoint is blocked.
• TLS/SSL validation failures: Self-signed certificates on private LLM deployments trigger HttpRequestException.
• Request timeouts: The default 10-minute timeout (OpenAIHttpClientHandlerUtil.GetHttpClient, line 98) may be insufficient for large embedding batches or slow local models.

Runtime Exceptions from the Semantic Kernel SDK

Unhandled exceptions from the underlying SDK—such as HttpRequestException, TaskCanceledException (timeout), or deserialization errors—bubble up through the kernel builder calls (e.g., builder.AddOpenAIChatCompletion in KernelService.cs, line 88). These typically surface in the API controller logs (e.g., OpenController.cs, lines 34-40).

Step-by-Step Debugging Steps for AntSK Model Connections

Follow this systematic approach to isolate and resolve connection failures.

1. Enable Development Logging

Set the environment variable to capture full request and response payloads:

export ASPNETCORE_ENVIRONMENT=Development

The OpenAIHttpClientHandler logs the rewritten URI and payload at lines 26-33 and 82-86 using Serilog.

2. Verify the AIModels Database Record

Inspect the configuration stored in the AIModels table:

var chatModel = _aIModels_Repositories.GetFirst(p => p.Id == app.ChatModelID);
Console.WriteLine($"Endpoint: {chatModel.EndPoint}");
Console.WriteLine($"Model: {chatModel.ModelName}");
Console.WriteLine($"Type: {chatModel.AIType}");

Ensure the EndPoint matches the regex pattern ^(https?)://([^/:]+)(:\d+)?/(.*) and includes the trailing slash if required.

3. Test Connectivity with a Raw HTTP Client

Bypass the Semantic Kernel pipeline to verify network reachability:

using AntSK.Domain.Utils;

var httpClient = OpenAIHttpClientHandlerUtil.GetHttpClient("http://localhost:11434/");
var payload = new
{
    model = "llama2",
    messages = new[] { new { role = "user", content = "Hello" } },
    stream = false
};
var json = System.Text.Json.JsonSerializer.Serialize(payload);
var response = await httpClient.PostAsync(
    "/v1/chat/completions",
    new StringContent(json, Encoding.UTF8, "application/json"));

Console.WriteLine(await response.Content.ReadAsStringAsync());

If this succeeds but the kernel fails, the issue lies in the AIType configuration or the kernel builder setup.

4. Inspect the Rewritten URL

Check the Serilog output for entries tagged with 【模型服务接口调用-<guid>,host:<EndPoint>】. Verify that the host and path match your expectations. If the host is missing or the path is truncated, the regex in OpenAIHttpClientHandler failed to parse the endpoint.

5. Validate the AI Type Switch

Set a breakpoint in KernelService.WithTextGenerationByAIType (lines 84-151) or KMService.WithTextGenerationByAIType (lines 93-124). Step through the switch statement to confirm the correct builder.Add* method is invoked for your provider (e.g., AddOpenAIChatCompletion for OpenAI, AddAzureOpenAIChatCompletion for Azure).

6. Adjust Timeout Settings

For slow local models or large embedding batches, increase the timeout in OpenAIHttpClientHandlerUtil.GetHttpClient:

// Line 98 in OpenAIHttpClientHandlerUtil.cs
httpClient.Timeout = TimeSpan.FromMinutes(20); // Increase from default 10 minutes

7. Review Controller Logs

Examine the exception details in the API controller (e.g., OpenController.cs lines 34-40). The Serilog output will contain the full stack trace from the Semantic Kernel SDK, revealing whether the failure is authentication (401), not found (404), or a network timeout.

8. Perform Network Diagnostics

From the host running AntSK, verify basic connectivity:

curl -v http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama2","messages":[{"role":"user","content":"hi"}]}'

If curl fails, the issue is environmental (firewall, DNS, or the model service is not running).

9. Isolate with Mock Services

Temporarily switch the AIType to Mock in the database to verify the rest of the pipeline:

// KernelService.cs lines 133-136
AIType.Mock => builder
    .AddMockTextCompletion()
    .AddMockChatCompletion()

If the application works with the mock, the failure is definitely in the external model configuration or network path.

Code Examples for Testing Model Connectivity

Testing the HTTP Handler Directly

Use this snippet to verify that OpenAIHttpClientHandler correctly rewrites URLs for your specific endpoint:

using System.Text;
using System.Text.Json;
using AntSK.Domain.Utils;

// Configure your actual endpoint from AIModels
string endpoint = "https://api.openai.com/v1/";
var httpClient = OpenAIHttpClientHandlerUtil.GetHttpClient(endpoint);

// Prepare a minimal chat completion request
var requestBody = new
{
    model = "gpt-3.5-turbo",
    messages = new[] 
    { 
        new { role = "system", content = "You are a helpful assistant." },
        new { role = "user", content = "Hello" }
    },
    temperature = 0.7
};

var json = JsonSerializer.Serialize(requestBody);
var content = new StringContent(json, Encoding.UTF8, "application/json");

try
{
    var response = await httpClient.PostAsync("/v1/chat/completions", content);
    var responseString = await response.Content.ReadAsStringAsync();
    
    Console.WriteLine($"Status: {response.StatusCode}");
    Console.WriteLine($"Response: {responseString}");
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Request failed: {ex.Message}");
}

This bypasses the Semantic Kernel entirely, isolating whether the issue is network-related or configuration-related.

Using Mock Models for Isolation

When you need to verify that your application logic works independently of external services, configure a mock model:

// First, create a mock model record in your database
var mockModel = new AIModels
{
    Id = "mock-debug-model",
    EndPoint = "http://localhost", // Not actually used
    ModelName = "mock-model",
    ModelKey = "fake-key",
    AIType = AIType.Mock  // Critical: set type to Mock
};

// Save to repository
_aIModels_Repositories.Insert(mockModel);

// Now use it with the kernel service
var app = new Apps { ChatModelID = mockModel.Id };
var kernel = kernelService.GetKernelByApp(app);

// Invoke a function - this will use the mock completion service
var result = await kernel.InvokeAsync(
    kernel.Plugins.GetFunction("ConversationSummaryPlugin", "SummarizeConversation"),
    new() { ["input"] = "Test input" });

Console.WriteLine(result.GetValue<string>());

The mock implementation is located in KernelService.cs at lines 133-136, where AddMockTextCompletion() and AddMockChatCompletion() are registered when AIType.Mock is detected.

Summary

• Model connection issues in AntSK originate from five distinct layers: database configuration (AIModels), HTTP handler rewriting (OpenAIHttpClientHandler), AI type selection (KernelService/KMService), network environment, and Semantic Kernel runtime exceptions.
• Verify the endpoint format in the database matches the regex ^(https?)://([^/:]+)(:\d+)?/(.*) and includes the correct scheme, host, and port.
• Use OpenAIHttpClientHandlerUtil.GetHttpClient to test connectivity outside the Semantic Kernel pipeline, isolating network issues from configuration errors.
• Check the AIType enum in KernelService.WithTextGenerationByAIType to ensure the correct builder method (OpenAI, AzureOpenAI, etc.) is invoked for your endpoint.
• Enable Development logging to capture the full rewritten URI and request/response payloads in Serilog, revealing exactly where the pipeline fails.

Frequently Asked Questions

Why does AntSK return a 404 error when connecting to my local Ollama instance?

A 404 error typically indicates that the EndPoint URL in the AIModels table is missing the trailing path segment or the ModelName does not exist on the Ollama server. Verify that the endpoint follows the format http://localhost:11434/ and that you have pulled the model (e.g., llama2) locally. Test with curl http://localhost:11434/v1/chat/completions to confirm the path is valid.

How can I increase the timeout for slow local LLM responses?

The default timeout is set to 10 minutes in OpenAIHttpClientHandlerUtil.GetHttpClient at line 98. To increase this for slow local models or large embedding batches, modify the HttpClient timeout before it is returned:

httpClient.Timeout = TimeSpan.FromMinutes(20);

Alternatively, when testing directly with OpenAIHttpClientHandlerUtil.GetHttpClient, set the timeout property on the returned instance before making the request.

What is the fastest way to verify if my API key is valid without modifying the database?

Use the raw HTTP client test approach with OpenAIHttpClientHandlerUtil.GetHttpClient to bypass the Semantic Kernel entirely. Pass your endpoint and construct a minimal chat completion request with your API key in the authorization header. If this returns a 401, your key is invalid or revoked. If it succeeds but the kernel fails, the issue is likely an AIType mismatch in the database configuration.

Why does my connection work with curl but fail in AntSK?

When curl succeeds but AntSK fails, the discrepancy usually lies in the OpenAIHttpClientHandler URL rewriting logic or the AIType selection. The handler parses the endpoint using a strict regex and reconstructs the URI; if your endpoint string lacks a trailing slash or includes unexpected query parameters, the rewritten URL may be malformed. Additionally, ensure the AIType enum value matches your service provider (OpenAI vs. AzureOpenAI), as the wrong builder method will generate incompatible request headers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}