Modern platforms for building AI agents significantly accelerate the development of such solutions. They allow you to easily select a large language model (LLM), manage prompts, and define tools that the agent can use automatically.

However, the real challenge on the developer’s side is ensuring the model receives the right context. Frameworks such as LangChain in Python or Semantic Kernel in .NET expect that with every request we provide conversation history or other data describing the current interaction state.

Intuitively, passing the entire conversation history every time seems reasonable. It should help the agent better understand context and make more accurate decisions. In practice, however, several questions arise:

• Does increasing the number of tokens in the prompt always improve responses?

• How do we avoid exceeding the context length limits of language models?

• What about the growing processing time and cost of subsequent agent calls?

In this article, I’ll show how to manage context passed to large language models using a .NET agent built with Semantic Kernel. I’ll present approaches that help control context size, ensuring stable costs and consistent solution quality.

Context Window – Limitation of LLMs

Large Language Models have a limit on the maximum context size, known as the context window. It includes all tokens used in a single model call — both input and output. Depending on the model, this limit can be, for example, 128k tokens (OpenAI GPT-5).

In practice, when building AI agents, this limit must include:

• system prompt

• conversation history

• tool outputs

• new context (e.g., user query or system event)

Since the context window also includes output tokens, too much input data reduces space available for reasoning and response generation.

Does More Context Always Help?

Intuitively, more context should improve results — but this is not always true. The paper Lost in the Middle: How Language Models Use Long Contexts shows that increasing the number of documents in a prompt eventually stops improving answer quality. Additionally, models tend to use information at the beginning and end of the context most effectively, while performing worst on information in the middle (the “lost in the middle” effect).

How to Manage AI Agent Context

If more context does not always improve results, the natural question is: how should we manage it?

This topic is explained in more detail in the article Cutting Through the Noise: Smarter Context Management for LLM-Powered Agents, which focuses on effective context management in systems based on LLMs.

In practice, there are two main approaches:

• LLM summarization – reducing the conversation history to a shorter version,

• Observation masking – limiting how much data is passed to the model.

Each approach has its trade-offs. Summarization controls the context size better, but it adds extra cost and may lose some details. Masking is simpler and cheaper, but it does not stop the context from growing over time.

In practice, the best results come from a hybrid approach that combines both methods. In the next sections, I will show how to implement them using Semantic Kernel in .NET.

Context Management in Semantic Kernel (.NET)

AI Product Recommendation Agent

Imagine an online computer store where an AI agent helps users choose a laptop based on preferences such as: budget, weight, battery life and use case. The agent gathers requirements step by step, searches products, analyzes descriptions, and provides recommendations.

First, we create a basic agent, and then we implement context management strategies — observation masking and LLM summarization. We will analyze their impact on the number of input tokens and total tokens using additional analytics built in the project.

The source code used in this article is available in the GitHub repository SemanticKernelContextManagement.

Basic AI Agent

To build the agent in .NET, we will use the Semantic Kernel framework. A simple “Hello World” example can be easily created based on the official documentation.

For this experiment, we will add a ProductsPlugin that returns information about laptops. To keep things simple, the data will be stored in static JSON files inside the project and loaded into memory.

For recommendations:

• A general one, which returns short information about all laptops:

[KernelFunction]
        [Description("Get all products from shop. Returns only product names and short summaries.")]
        public string GetProducts()
        {
            var productSummaries = products.Select(p => new
            {
                p.Name,
                p.ShortSummary,
            });

            return JsonSerializer.Serialize(productSummaries, ProductJsonOptions);
        }

A detailed one, for a single product (laptop):

        [Description("Get full detailed description of a product by its name.")]
        public string GetProductDetails([Description("Product name, e.g. Laptop Pro 14")] string productName)
        {
            var product = products.FirstOrDefault(p => p.Name.Equals(productName, StringComparison.OrdinalIgnoreCase));
            if (product == null)
            {
                return $"Product not found: {productName}";
            }

            return JsonSerializer.Serialize(product, ProductJsonOptions);
        }

In the first request, we also include a system prompt that tells the model to act as a shop assistant. One useful advantage of such an agent is that the assistant will always reply in the user’s language 🙂:

private const string SystemPrompt = """
            You are a shop assistant that recommends products from our catalog.
            Use the Products plugin (GetProducts, GetProductDetails) to read real catalog data before suggesting items.
            Do not invent products, prices, or stock. If nothing matches, say so clearly.
            Match the user's language in your replies.
            """;

In Semantic Kernel, we can decide whether the agent should use the tools defined in the plugin. In this case, we use FunctionChoiceBehavior.Auto, which means the agent can use the functions, but it is not required to:

        private readonly OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
        {
            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
        };

We build the program as a console application. We take the user’s request from the console, for example: “I want to buy a laptop.” In the basic approach, we add the question to the context as a UserMessage and send everything to the LLM. After receiving the response, we also save it in the history and return it to the user:

    public async Task<string> GetRecommendationAsync(string userInput)
    {
        ChatHistory.AddUserMessage(userInput);

        var result = await chatCompletionService.GetChatMessageContentAsync(
            ChatHistory,
            executionSettings: openAIPromptExecutionSettings,
            kernel: kernel);

        if (string.IsNullOrWhiteSpace(result.Content))
        {
            throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
        }

        ChatHistory.Add(result);
        return result.Content;
    }

Example conversation with the assistant in the console:

Observation masking

In agents built on the Semantic Kernel platform, raw tool results are added one below another to the conversation history as messages with the role AuthorRole.Tool. They are not visible to the client of our store. We return to the user a response processed by the agent, generated based on those results.

In the case of the function GetProductDetails, the result is a JSON containing full information about a specific laptop. Let’s assume that in most use cases, the same product information will be included in the response generated by the assistant. We make a deliberate decision to introduce observation masking. In this way, we reduce costs and response time in exchange for lower quality — a higher risk of hallucinations and a possible increase in the number of repeated tool calls.

We mask tool results by introducing a placeholder in their place:

private const string ObservationMaskedPlaceholder = "[TOOL_OBSERVATION_MASKED]";

We introduce the mechanism just before returning the response to the client, so that it takes effect for the next user query:

    public async Task<string> GetRecommendationAsync(string userInput)
    {
        ChatHistory.AddUserMessage(userInput);

        var result = await chatCompletionService.GetChatMessageContentAsync(
            ChatHistory,
            executionSettings: openAIPromptExecutionSettings,
            kernel: kernel);

        if (string.IsNullOrWhiteSpace(result.Content))
        {
            throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
        }

        ChatHistory.Add(result);

        // maskowanie obserwacji
        if (useObservationMasking)
        {
            MaskObservations();
        }

        return result.Content;
    }

        private void MaskObservations()
        {
            var toolMessages = ChatHistory.Where(m => m.Role == AuthorRole.Tool);
            foreach (var message in toolMessages)
            {
                message.Content = ObservationMaskedPlaceholder;

                if (message.Items.Count == 0)
                {
                    message.Items.Add(new TextContent(ObservationMaskedPlaceholder));
                    continue;
                }

                var originals = message.Items.ToArray();
                message.Items.Clear();

                foreach (var item in originals)
                {
                    if (item is FunctionResultContent functionResult)
                    {
                        message.Items.Add(new FunctionResultContent(
                            functionResult.FunctionName,
                            functionResult.PluginName,
                            functionResult.CallId,
                            ObservationMaskedPlaceholder));
                    }
                    else
                    {
                        message.Items.Add(new TextContent(ObservationMaskedPlaceholder));
                    }
                }
            }
        }

LLM summarization

Let’s imagine that customers of our store ask many questions about laptops during a single conversation. As the interaction history grows, the number of tokens sent to the model increases. As a result, subsequent responses are generated more and more slowly, the processing cost grows linearly, and the quality of the responses does not significantly improve. In this situation, we can deliberately introduce periodic AI-based summarization of the context. It allows us to control the size of the transmitted data, stabilizing both cost and response time. In the case of an asynchronous approach, the impact on latency is minimal. However, this comes at the cost of increased solution complexity and the risk of losing some information.

Next to our agent, we add a query that will be executed after every 10 turns with the user. It is worth noting that we trigger this mechanism after masking the observations, when we use the hybrid approach:

        public async Task<string> GetRecommendationAsync(string userInput)
        {
            ChatHistory.AddUserMessage(userInput);

            var result = await chatCompletionService.GetChatMessageContentAsync(
                ChatHistory,
                executionSettings: openAIPromptExecutionSettings,
                kernel: kernel);

            if (string.IsNullOrWhiteSpace(result.Content))
            {
                throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
            }

            ChatHistory.Add(result);

            if (useObservationMasking)
            {
                MaskObservations();
            }

            // Dodanie summarization
            if (useSummarization)
            {
                var numberOfTurnsWithUser = ChatHistory.Count(c => c.Role == AuthorRole.User);
                if (numberOfTurnsWithUser % 10 == 0)
                {
                    await SummarizeChatAsync();
                }
            }

            return result.Content;
        }

The summarization process can use a different, cheaper model than the main agent, because it does not require high-quality response generation, only information compression. In our case, for simplicity, we reuse Semantic Kernel. However, for this query, we send a separate system prompt:

        private const string SummarizationSystemPrompt = """
            You compress conversation transcripts for a product-recommendation assistant.
            Preserve concrete facts the user asked about, product names, prices, stock, and language the user used.
            Do not invent catalog data. Output a concise third-person summary suitable as context for continuing the chat.
            """;

we disable the ability to use tools:

        private readonly OpenAIPromptExecutionSettings summarizationPromptExecutionSettings = new()
        {
            FunctionChoiceBehavior = FunctionChoiceBehavior.None()
        };

and we also build a separate chat history as a transcript of the conversation so far between the agent and the user:

        private static string FormatConversationForSummary(ChatHistory history)
        {
            var blocks = new List<string>();
            foreach (var message in history)
            {
                if (message.Role == AuthorRole.System)
                {
                    continue;
                }

                var parts = new List<string>();
                if (!string.IsNullOrWhiteSpace(message.Content))
                {
                    parts.Add(message.Content.Trim());
                }

                foreach (var item in message.Items)
                {
                    switch (item)
                    {
                        case FunctionCallContent call:
                            parts.Add($"[called {call.PluginName}.{call.FunctionName} with arguments: {call.Arguments}]");
                            break;

                        case FunctionResultContent result:
                            parts.Add($"[result from {result.PluginName}.{result.FunctionName}: {FormatResultObject(result.Result)}]");
                            break;

                        case TextContent text when !string.IsNullOrWhiteSpace(text.Text):
                            parts.Add(text.Text.Trim());
                            break;
                    }
                }

                var body = parts.Count > 0 ? string.Join(" ", parts) : "(no text)";
                blocks.Add($"{message.Role}: {body}");
            }

            return string.Join(Environment.NewLine + Environment.NewLine, blocks);
        }

Finally, we send a request for a summary, and from the response we create a new context for the AI agent, adding the original system prompt once again:

private async Task SummarizeChatAsync()
{
    var systemMessage = ChatHistory.FirstOrDefault(m => m.Role == AuthorRole.System);
    if (systemMessage is null)
    {
        return;
    }

    var transcript = FormatConversationForSummary(ChatHistory);
    if (string.IsNullOrWhiteSpace(transcript))
    {
        return;
    }

    var summarizationChat = new ChatHistory();
    summarizationChat.AddSystemMessage(SummarizationSystemPrompt);
    summarizationChat.AddUserMessage(
        "Summarize the following conversation transcript.\n\n" + transcript);

    var summaryResponse = await chatCompletionService.GetChatMessageContentAsync(
        summarizationChat,
        executionSettings: summarizationPromptExecutionSettings,
        kernel: null);

    if (string.IsNullOrWhiteSpace(summaryResponse.Content))
    {
        throw new InvalidOperationException("Summarization did not return any content.");
    }

    var shopSystemText = systemMessage.Content ?? string.Empty;
    ChatHistory.Clear();
    ChatHistory.AddSystemMessage(shopSystemText);
    ChatHistory.AddUserMessage("Summary of the conversation so far:\n" + summaryResponse.Content);
}

Comparison of context management strategies based on a 21-turn conversation

The prepared system should be tested to prove the effectiveness of token reduction mechanisms.

I prepared a 21-turn conversation, which I ran in 4 scenarios:

• without context management (Basic),

• only observation masking (Omasking),

• only LLM summarization (Summarization),

• Observation masking and LLM summarization (OMask+Summ).

These are all the questions (translated to English):

1. List all products from the catalog with a short description of each.
2. I am looking for a laptop for programming and mobile work — what do you recommend and why?
3. I need something for gaming — which model makes sense and what are its key parameters?
4. Compare Laptop Pro 14 with DevBook 15 for a developer (.NET, VS / VS Code).
5. What is the exact technical description of the Creator Studio 16 model? List the specifications and use cases.
6. And Campus Note 14 — who is it for and how is it different from BalanceBook 14?
7. UltraLite 13 vs Silent Lite 13: which one is lighter or more “mobile” according to the catalog data?
8. Provide product details of Gaming Max 17 — CPU, RAM, display, weight if available in the description.
9. Do you have anything below a 14-inch screen? List models from the catalog that match.
10. Suggest a set: a laptop for studying at university and briefly justify each model in one sentence.
11. Let’s go back to Laptop Pro 14: repeat the most important advantages and limitations from the description.
12. Silent Lite 13 — full description with details; I am interested in the battery and display.
13. DevBook 15 — details from the catalog: what workloads is it suitable for and what is it not suitable for?
14. Does any laptop have a clear focus on silence or mobility in the description? Indicate which one and why.
15. I need something for photo/video (creator workflow) — what do you choose from the catalog and why?
16. BalanceBook 14 — full product details from the catalog.
17. Again, list all product names, but only names in one line, without descriptions.
18. Campus Note 14 — technical details and who it is for according to the full description.
19. If budget is not a concern: which one laptop would you recommend as “universal” and why?
20. Briefly compare three models: Gaming Max 17, Creator Studio 16, Laptop Pro 14 — who are they for.
21. Summarize our entire conversation: which models I considered and what you finally recommend.

I did not notice a significant difference in quality between the model’s responses in each scenario. For each of them, I measured the number of input tokens and total tokens for every interaction with the model and presented them on charts:

Example input tokens in different strategies

Absolute values:

% compared to Basic:

Reduction vs Basic:

As expected, applying observation masking led to a stable reduction in the number of input tokens at the level of about 35–40% compared to the baseline approach (except for the first turn).

In turn, LLM summarization caused a clear drop in the number of tokens after the 10th turn, reaching a reduction of around 93% in later interactions.

The hybrid approach combined both effects, providing a reduction in the number of tokens both before and after performing summarization.

Conclusions

The way AI agents manage context is an architectural decision that has a direct impact on cost, response time, quality, and scalability of the solution, and it should depend on the nature of the application.

Passing the full conversation history is not a scalable approach — as the interaction grows, the number of tokens increases, which leads to higher costs and longer response times without proportional improvement in quality.

Observation masking is a simple and effective mechanism for reducing tokens, which helps limit the “noise” coming from tool responses. However, it does not solve the problem of growing context in the long term.

LLM summarization makes it possible to control the context length by compressing it. In the analyzed scenario, it allowed reducing the number of tokens by over 90%, at the cost of an additional model call and potential loss of some information.

The best results are achieved with a hybrid approach, which combines both mechanisms — it reduces the number of tokens in every interaction (except the first one) and controls long-term context growth.

Your turn

How are you handling context growth in your AI agents?
Have you tried masking or summarization in production?

If you’re working with AI systems, feel free to share your approach — I’m always curious how others solve this.

And if this kind of content is useful to you, consider following for more articles on .NET, AI, and technical decisions.

Nowoczesne platformy do budowania agentów AI znacząco przyspieszają tworzenie takich rozwiązań. Pozwalają w prosty sposób wybrać duży model językowy (LLM), zarządzać promptami oraz definiować narzędzia (tools), z których agent może korzystać automatycznie.

Prawdziwym wyzwaniem po stronie programisty pozostaje jednak zapewnienie odpowiedniego kontekstu dla modelu. Frameworki takie jak LangChain w Pythonie czy Semantic Kernel w .NET oczekują, że przy każdym zapytaniu przekażemy historię rozmowy lub inne dane opisujące aktualny stan interakcji.

Intuicyjnie przekazywanie całej historii rozmowy za każdym razem do agenta wydaje się rozsądnym podejściem. Powinno to pozwolić agentowi lepiej rozumieć kontekst i podejmować trafniejsze decyzje. W praktyce pojawia się jednak kilka pytań:

• Czy większa liczba tokenów w promptcie zawsze prowadzi do lepszych odpowiedzi?

• Jak nie przekroczyć limitu długości kontekstu poszczególnych modeli językowych?

• Co zrobić z rosnącym czasem przetwarzania i kosztem kolejnych wywołań agenta?

W tym artykule pokażę, jak zarządzać kontekstem przekazywanym do dużych modeli językowych na przykładach w .NET agenta zbudowanego na platformie Semantic Kernel. Omówię podejścia, które pozwalają kontrolować rozmiar kontekstu, a tym samym zapewnić stabilność kosztów oraz jakość działania rozwiązań opartych na agentach AI.

Context window – podstawowe ograniczenie LLM

Modele językowe mają ograniczenie na maksymalny rozmiar kontekstu nazywane context window. Obejmuje ono wszystkie tokeny używane podczas jednego wywołania modelu — zarówno wejściowe, jak i wyjściowe. W zależności od modelu limit to np. 128k tokenów (OpenAI GPT-5).

W praktyce, przy budowie agentów AI oznacza to, że w tym limicie muszą zmieścić się między innymi:

• prompt systemowy,

• historia rozmowy,

• wyniki narzędzi (tool outputs),

• nowy kontekst dostarczony do agenta, np. pytanie użytkownika lub zdarzenie z systemu.

Ponieważ context window obejmuje również tokeny wyjściowe, zbyt dużo danych na wejściu może spowodować, że model będzie miał mniej przestrzeni na proces wnioskowania (reasoning) oraz wygenerowanie odpowiedzi.

Czy więcej kontekstu zawsze pomaga?

Intuicyjnie więcej kontekstu powinno poprawiać wyniki. W praktyce nie zawsze tak jest. W pracy Lost in the Middle: How Language Models Use Long Contexts pokazano, że zwiększanie liczby dokumentów w promptcie przestaje poprawiać jakość odpowiedzi mimo rosnącej liczby trafnych danych. Dodatkowo modele najlepiej wykorzystują informacje z początku i końca kontekstu, a najgorzej te znajdujące się w jego środku (tzw. Lost in the Middle).

Jak zarządzać kontekstem agentów AI

Skoro większy kontekst nie zawsze prowadzi do lepszych wyników, pojawia się naturalne pytanie - jak zarządzać kontekstem agentów AI?

Temat ten został szerzej opisany w artykule Cutting Through the Noise: Smarter Context Management for LLM-Powered Agents dotyczącym efektywnego zarządzania kontekstem w systemach opartych na LLM. W praktyce stosuje się dwa główne podejścia:

• LLM summarization – kompresowanie historii do krótszej formy

• observation masking – ograniczanie liczby przekazywanych danych

Każde z nich ma swoje trade-offy: summarization lepiej kontroluje rozmiar kontekstu, ale generuje dodatkowy koszt i może gubić szczegóły. Masking jest prostszy i tańszy, ale nie zapobiega nieograniczonemu wzrostowi kontekstu. W praktyce najlepsze rezultaty daje podejście hybrydowe, łączące oba mechanizmy. W kolejnych sekcjach pokażę, jak zaimplementować je przy użyciu Semantic Kernel w .NET.

Zarządzanie kontekstem agentów AI w Semantic Kernel .NET

Agent AI rekomendujący produkty

Wyobraźmy sobie sklep internetowy ze sprzętem komputerowym, w którym agent AI pomaga użytkownikowi wybrać laptop na podstawie preferencji, takich jak budżet, waga, czas pracy baterii czy zastosowanie. Agent, krok po kroku zbiera wymagania użytkownika, wyszukuje pasujące produkty, analizuje ich opisy i rekomenduje sprzęt.

Na początku tworzymy podstawowego agenta, a następnie implementujemy strategie zarządzania kontekstem - observation masking oraz LLM summarization. Przeanalizujemy ich wpływ na liczbę zużytych tokenów wejścia (input tokens) i tokenów całościowych (total tokens) na podstawie dodatkowych mechanizmów analitycznych zbudowanych w ramach projektu.

Kod źródłowy, którego fragmenty znajdują się w artykule dostępny jest w repozytorium GitHub SemanticKernelContextManagement.

Podstawowy agent AI

Do stworzenia agenta w .NET wykorzystamy framework Semantic Kernel, którego przykład typu "Hello World" łatwo zbudować na podstawie oficjalnej dokumentacji. Na potrzeby eksperymentu wyposażymy go w ProductsPlugin, który zwróci informacje o laptopach, które dla ułatwienia będą zawarte w projekcie w statycznych plikach JSON i wczytane do pamięci programu. Do rekomendacji:

• Ogólnej, która zwraca skrócone informacje o wszystkich laptopach:

          [KernelFunction]
          [Description("Get all products from shop. Returns only product names and short summaries.")]
          public string GetProducts()
          {
              var productSummaries = products.Select(p => new
              {
                  p.Name,
                  p.ShortSummary,
              });
  
              return JsonSerializer.Serialize(productSummaries, ProductJsonOptions);
          }
  

• Szczegółowej, dotyczącej jednego produktu (laptopa):

        [Description("Get full detailed description of a product by its name.")]
        public string GetProductDetails([Description("Product name, e.g. Laptop Pro 14")] string productName)
        {
            var product = products.FirstOrDefault(p => p.Name.Equals(productName, StringComparison.OrdinalIgnoreCase));
            if (product == null)
            {
                return $"Product not found: {productName}";
            }

            return JsonSerializer.Serialize(product, ProductJsonOptions);
        }

W pierwszym zapytaniu przekazujemy dodatkowo system prompt, który instruuje, że model ma się wcielić w rolę asystenta w sklepie. Z zalet warto zwrócić uwagę, że asystent zawsze odpowie w języku rozmówcy 🙂:

        private const string SystemPrompt = """
            You are a shop assistant that recommends products from our catalog.
            Use the Products plugin (GetProducts, GetProductDetails) to read real catalog data before suggesting items.
            Do not invent products, prices, or stock. If nothing matches, say so clearly.
            Match the user's language in your replies.
            """;

W Semantic Kernel możemy zdecydować, czy agent powinien skorzystać ze zdefiniowanych narzędzi w plugin. W tym wypadku użyjemy FunctionChoiceBehavior.Auto co oznacza, że może skorzystać z funkcji, ale nie musi:

        private readonly OpenAIPromptExecutionSettings openAIPromptExecutionSettings = new()
        {
            FunctionChoiceBehavior = FunctionChoiceBehavior.Auto()
        };

Program tworzymy jako aplikację konsolową. Z konsoli pobieramy zapytanie klienta sklepu, przykładowo "Chcę kupić laptopa". W podstawowym podejściu dodajemy pytanie do kontekstu jako UserMessage i wysyłamy całość do LLM. Po otrzymaniu odpowiedzi zapisujemy ją również w historii i zwracamy do użytkownika:

        public async Task<string> GetRecommendationAsync(string userInput)
        {
            ChatHistory.AddUserMessage(userInput);

            var result = await chatCompletionService.GetChatMessageContentAsync(
                ChatHistory,
                executionSettings: openAIPromptExecutionSettings,
                kernel: kernel);

            if (string.IsNullOrWhiteSpace(result.Content))
            {
                throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
            }

            ChatHistory.Add(result);
            return result.Content;
        }

Przykładowy dialog w konsoli:

Maskowanie obserwacji (observation masking)

W agentach zbudowanych na platformie Semantic Kernel surowe wyniki narzędzi trafiają jeden pod drugim do historii rozmowy jako wiadomości z przypisaną rolą AuthorRole.Tool. Nie są one widoczne dla klienta naszego sklepu. Zwracamy użytkownikowi przetworzoną przez agenta odpowiedź, wygenerowaną właśnie na podstawie tych wyników.

W przypadku funkcji GetProductDetails wynikiem jest JSON zawierający pełne informacje o konkretnym laptopie. Załóżmy, że w większości przypadków użycia te same informacje o produkcie trafią do wygenerowanej przez asystenta odpowiedzi. Podejmujemy świadomą decyzję o wprowadzeniu maskowania obserwacji. W ten sposób zmniejszamy koszty i czas oczekiwania na odpowiedź w zamian za obniżenie jakości - większe ryzyko halucynacji oraz ewentualne zwiększenie ilości ponownych wywołań narzędzi.

Maskujemy wyniki narzędzi przez wprowadzenie w ich miejsce placeholdera:

private const string ObservationMaskedPlaceholder = "[TOOL_OBSERVATION_MASKED]";

Mechanizm wprowadzamy, tuż przed zwróceniem odpowiedzi do klienta, tak by zadziałał on dla kolejnego zapytania użytkownika:

        public async Task<string> GetRecommendationAsync(string userInput)
        {
            ChatHistory.AddUserMessage(userInput);

            var result = await chatCompletionService.GetChatMessageContentAsync(
                ChatHistory,
                executionSettings: openAIPromptExecutionSettings,
                kernel: kernel);

            if (string.IsNullOrWhiteSpace(result.Content))
            {
                throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
            }

            ChatHistory.Add(result);

            // maskowanie obserwacji
            if (useObservationMasking)
            {
                MaskObservations();
            }

            return result.Content;
        }

        private void MaskObservations()
        {
            var toolMessages = ChatHistory.Where(m => m.Role == AuthorRole.Tool);
            foreach (var message in toolMessages)
            {
                message.Content = ObservationMaskedPlaceholder;

                if (message.Items.Count == 0)
                {
                    message.Items.Add(new TextContent(ObservationMaskedPlaceholder));
                    continue;
                }

                var originals = message.Items.ToArray();
                message.Items.Clear();

                foreach (var item in originals)
                {
                    if (item is FunctionResultContent functionResult)
                    {
                        message.Items.Add(new FunctionResultContent(
                            functionResult.FunctionName,
                            functionResult.PluginName,
                            functionResult.CallId,
                            ObservationMaskedPlaceholder));
                    }
                    else
                    {
                        message.Items.Add(new TextContent(ObservationMaskedPlaceholder));
                    }
                }
            }
        }

Podsumowywanie kontekstu przez LLM (LLM summarization)

Wyobraźmy sobie, że klienci naszego sklepu zadają wiele pytań o laptopy w trakcie jednej rozmowy. Wraz z rosnącą historią interakcji zwiększa się liczba tokenów przekazywanych do modelu. W efekcie kolejne odpowiedzi są generowane coraz wolniej, koszt ich przetwarzania rośnie liniowo, a jakość odpowiedzi nie ulega istotnej poprawie. W tej sytuacji możemy świadomie wprowadzić okresowe podsumowywanie przez AI kontekstu. Pozwala ono kontrolować rozmiar przekazywanych danych, stabilizując koszt i czas odpowiedzi. W przypadku podejścia asynchronicznego wpływ na latency jest minimalny. Odbywa się to jednak kosztem większej złożoności rozwiązania oraz ryzyka utraty części informacji.

Obok naszego agenta dodajemy zapytanie, które będzie wykonywane po każdych 10 turach z użytkownikiem. Warto zaznaczyć, że mechanizm wywołujemy już po zamaskowaniu obserwacji, gdy korzystamy z podejścia hybrydowego:

        public async Task<string> GetRecommendationAsync(string userInput)
        {
            ChatHistory.AddUserMessage(userInput);

            var result = await chatCompletionService.GetChatMessageContentAsync(
                ChatHistory,
                executionSettings: openAIPromptExecutionSettings,
                kernel: kernel);

            if (string.IsNullOrWhiteSpace(result.Content))
            {
                throw new InvalidOperationException($"{nameof(chatCompletionService)} did not return any content.");
            }

            ChatHistory.Add(result);

            if (useObservationMasking)
            {
                MaskObservations();
            }

            // Dodanie summarization
            if (useSummarization)
            {
                var numberOfTurnsWithUser = ChatHistory.Count(c => c.Role == AuthorRole.User);
                if (numberOfTurnsWithUser % 10 == 0)
                {
                    await SummarizeChatAsync();
                }
            }

            return result.Content;
        }

Proces podsumowywania może korzystać z innego, tańszego modelu niż główny agent, ponieważ nie wymaga on wysokiej jakości generowania odpowiedzi, a jedynie kompresji informacji. W naszym przypadku dla ułatwienia reużywamy Semantic Kernel. Jednak dla tego zapytania wysyłamy osobny system prompt:

private const string SummarizationSystemPrompt = """
    You compress conversation transcripts for a product-recommendation assistant.
    Preserve concrete facts the user asked about, product names, prices, stock, and language the user used.
    Do not invent catalog data. Output a concise third-person summary suitable as context for continuing the chat.
    """;

wyłączamy możliwość korzystania z tools:

   private readonly OpenAIPromptExecutionSettings summarizationPromptExecutionSettings = new()
{
    FunctionChoiceBehavior = FunctionChoiceBehavior.None()
};

oraz budujemy osobne chat history jako transkrypt z dotychczasowej rozmowy między agentem, a użytkownikiem:

private string FormatConversationForSummary()
{
    var blocks = new List<string>();
    foreach (var message in ChatHistory)
    {
        if (message.Role == AuthorRole.System)
        {
            continue;
        }

        var parts = new List<string>();
        if (!string.IsNullOrWhiteSpace(message.Content))
        {
            parts.Add(message.Content.Trim());
        }

        foreach (var item in message.Items)
        {
            switch (item)
            {
                case FunctionCallContent call:
                    parts.Add($"[called {call.PluginName}.{call.FunctionName} with arguments: {call.Arguments}]");
                    break;

                case FunctionResultContent result:
                    parts.Add($"[result from {result.PluginName}.{result.FunctionName}: {FormatResultObject(result.Result)}]");
                    break;

                case TextContent text when !string.IsNullOrWhiteSpace(text.Text):
                    parts.Add(text.Text.Trim());
                    break;
            }
        }

        var body = parts.Count > 0 ? string.Join(" ", parts) : "(no text)";
        blocks.Add($"{message.Role}: {body}");
    }

    return string.Join(Environment.NewLine + Environment.NewLine, blocks);
}

Ostatecznie wysyłamy request o summary, i z odpowiedzi tworzymy nowy kontekst dla agenta AI, dodając jeszcze raz oryginalny system prompt.

private async Task SummarizeChatAsync()
{
    var transcript = FormatConversationForSummary();

    var summarizationChat = new ChatHistory();
    summarizationChat.AddSystemMessage(SummarizationSystemPrompt);
    summarizationChat.AddUserMessage(
        "Summarize the following conversation transcript.\n\n" + transcript);

    var summaryResponse = await chatCompletionService.GetChatMessageContentAsync(
        summarizationChat,
        executionSettings: summarizationPromptExecutionSettings,
        kernel: null);

    if (string.IsNullOrWhiteSpace(summaryResponse.Content))
    {
        throw new InvalidOperationException("Summarization did not return any content.");
    }

    NotifySummarizationTokenUsed(summaryResponse);

    ChatHistory.Clear();
    ChatHistory.AddSystemMessage(SystemPrompt);
    ChatHistory.AddUserMessage("Summary of the conversation so far:\n" + summaryResponse.Content);
}

Porównanie strategii zarządzania kontekstem na przykładzie 21-turowej rozmowy

Przygotowany system należy przetestować, by udowodnić skuteczność mechanizmów redukcji tokenów.

Przygotowałem 21-turową rozmowę, którą przeprowadziłem w 4 scenariuszach:

1. Bez zarządzania kontekstem (Basic).

2. Tylko maskowanie obserwacji (Omasking).

3. Wyłącznie LLM summarization (Summarization).

4. Maskowanie obserwacji oraz LLM Summarization (OMask+Summ).

To wszystkie pytania:

1. Wypisz wszystkie produkty z katalogu z krótkim opisem każdego.
2. Szukam laptopa pod programowanie i pracę mobilną — co polecasz i dlaczego?
3. Potrzebuję czegoś do gier — który model ma sens i jakie ma kluczowe parametry?
4. Porównaj Laptop Pro 14 z DevBook 15 pod kątem developera (.NET, VS / VS Code).
5. Jaki jest dokładny opis techniczny modelu Creator Studio 16? Wypisz specyfikację i zastosowania.
6. A Campus Note 14 — dla kogo jest i czym różni się od BalanceBook 14?
7. UltraLite 13 vs Silent Lite 13: który jest lżejszy lub bardziej „mobilny” według danych z katalogu?
8. Podaj szczegóły produktu Gaming Max 17 — CPU, RAM, ekran, wagę jeśli są w opisie.
9. Czy masz coś poniżej 14 cali ekranu? Wymień modele z katalogu, które pasują.
10. Zaproponuj zestaw: laptop do nauki na uczelnię i krótko uzasadnij jednym zdaniem na model.
11. Wróćmy do Laptop Pro 14: powtórz najważniejsze zalety i ograniczenia z opisu.
12. Silent Lite 13 — pełny opis z szczegółami; interesuje mnie bateria i wyświetlacz.
13. DevBook 15 — szczegóły z katalogu: dla jakich obciążeń się nadaje, a dla jakich nie?
14. Czy któryś laptop ma wyraźny nacisk na ciszę lub mobilność w opisie? Wskaż który i dlaczego.
15. Potrzebuję czegoś do photo/video (creator workflow) — co wybierasz z katalogu i dlaczego?
16. BalanceBook 14 — pełne szczegóły produktu z katalogu.
17. Znowu lista wszystkich nazw produktów, ale tylko nazwy w jednej linii, bez opisów.
18. Campus Note 14 — szczegóły techniczne i dla kogo jest według długiego opisu.
19. Jeśli budżet nie gra roli: jaki jeden laptop byś polecił „universal” i dlaczego?
20. Porównaj krótko trzy modele: Gaming Max 17, Creator Studio 16, Laptop Pro 14 — kto dla kogo.
21. Podsumuj całą naszą rozmowę: jakie modele brałem pod uwagę i co finalnie rekomendujesz.

Nie zauważyłem znaczącej różnicy jakości między odpowiedziami modelu w każdym scenariuszu. Dla każdego z nich zmierzyłem ilość tokenów wejściowych (input tokens) oraz total tokens każdej interakcji z modelem i przedstawiłem na wykresach:

Przykładowe input tokens w poszczególnych strategiach

Wartości bezwzględne:

% względem Basic:

Redukcja vs Basic:

Zgodnie z oczekiwaniami zastosowanie maskowania obserwacji doprowadziło do stabilnej redukcji liczby tokenów wejściowych na poziomie około 35–40% względem podejścia bazowego (poza pierwszą turą).

Z kolei LLM summarization spowodowało wyraźny spadek liczby tokenów po 10 turze, osiągając redukcję rzędu 93% w dalszych interakcjach.

Podejście hybrydowe połączyło oba efekty, zapewniając redukcję liczby tokenów zarówno przed, jak i po wykonaniu summarization.

Wnioski

Sposób zarządzania kontekstem agentów AI jest decyzją architektoniczną, która ma bezpośredni wpływ na koszt, czas odpowiedzi, jakość oraz skalowalność rozwiązania i powinien być uzależniony od charakteru aplikacji.

Przekazywanie pełnej historii rozmowy nie jest podejściem skalowalnym — wraz z długością interakcji rośnie liczba tokenów, co prowadzi do zwiększenia kosztów i czasu odpowiedzi bez proporcjonalnej poprawy jakości.

Observation masking stanowi prosty i efektywny mechanizm redukcji tokenów, który pozwala ograniczyć „szum” wynikający z odpowiedzi narzędzi. Nie rozwiązuje jednak problemu rosnącego kontekstu w dłuższej perspektywie.

LLM summarization umożliwia kontrolowanie długości kontekstu poprzez jego kompresję. W badanym scenariuszu pozwoliło to osiągnąć redukcję liczby tokenów nawet o ponad 90%, kosztem dodatkowego wywołania modelu oraz potencjalnej utraty części informacji.

Najlepsze rezultaty osiąga podejście hybrydowe, które łączy oba mechanizmy — redukuje liczbę tokenów w każdej interakcji (poza pierwszą) oraz kontroluje długoterminowy wzrost kontekstu.

Identyfikatory obiektów (ID) odgrywają kluczową rolę w systemach backendowych i rozproszonych. Zwykle do identyfikacji stosujemy klucze zastępcze (surrogate keys) – generowane losowo (np. GUID) lub sekwencyjnie w bazie danych. Istnieje jednak inne podejście, użycie kluczy naturalnych. W tym przypadku id wyliczane są w przewidywalny sposób na podstawie danych biznesowych.

W artykule pokażę, w jakich sytuacjach zastosowanie deterministycznych identyfikatorów może przyspieszyć odczyty i uprościć integracje w naszych aplikacjach.

Jak deterministyczne ID upraszczają pracę z CosmosDB

Korzyści przy odczytach

Jeśli generowanie klucza w bazie danych odbywa się po stronie klienta, największym ryzykiem jest duplikacja. W praktyce często stosujemy Guid.NewGuid(), co redukuje prawdopodobieństwo kolizji niemal do zera. W bardziej złożonych scenariuszach zdarza się jednak, że powołujemy osobne serwisy do generowania kluczy.

W przypadku pracy z bezserwerową bazą danych NoSQL Azure Cosmos DB sytuacja wygląda inaczej. Pole id nie jest globalnie unikalne – musi być niepowtarzalne tylko w obrębie jednej partycji. Prawdziwa tożsamość dokumentu to para (partitionKey, id). Jeśli zaprojektujemy ją w przewidywalny sposób, zyskamy prostsze i szybsze operacje.

Przykładem może być system fakturowy w sklepie, w którym kluczem partycji jest identyfikator klienta, a id to ten sam identyfikator rozszerzony o numer zamówienia. Dokument o numerze C123-2025/09/001 w partycji klienta C123 ma wtedy tożsamość: partitionKey = "C123", id = "C123-2025/09/001". Wyszukanie faktury dla konkretnego zamówienia sprowadza się wówczas do jednoznacznego odczytu o złożoności O(1). W rozwiązaniu wykorzystującym klucz zastępczy należałoby wykonać zapytanie:

/*/ Przykładowe query w języku NoSQL używanym w CosmosDB /*/
SELECT TOP 1 c
FROM c
WHERE c.orderNumber = "C123-2025/09/001"

Oznacza to przeszukiwanie całej partycji to jest przejście przez nią jeden raz aż do znalezienia wyniku. Złożonośc takiego algorytmu to O(n).

Korzyści przy zapisie

Zalety stosowania kluczy naturalnych widać także przy zapisie. Wyobraźmy sobie, że faktury przechodzą w aplikacji kilka etapów – od szkicu po wersję finalną.

• Przy korzystaniu z identyfikatorów Guid.NewGuid() trzeba najpierw wykonać krok A, czyli wygenerować identyfikator albo odczytać go z bazy, a dopiero potem przekazać dalej.

• Dodanie tej samej faktury nie jest wtedy idempotentne. Zabezpieczenie przed duplikatami wymaga dodatkowych odczytów i logiki w kodzie.

Stosując deterministyczne identyfikatory możemy od razu uruchamiać równolegle różne procesy korzystające z tego samego klucza. Dzięki temu całość działa szybciej i bardziej niezależnie. Unikamy duplikatów, a kod staje się prostszy.

Kiedy nie stosować kluczy naturalnych

Nie każde pole biznesowe nadaje się do roli identyfikatora:

• Adres e-mail użytkownika czy nazwa produktu – to pola mutowalne, które w naturalny sposób ulegają zmianom.

• PESEL i inne dane wrażliwe – nie powinny być używane jako klucze ani powielane w bazie bez uzasadnienia.

Użycie takich pól jako kluczy prowadziłoby do kolizji, problemów migracyjnych oraz ryzyka niezamierzonej ekspozycji danych wrażliwych (np. w logach, adresach URL czy systemach integracyjnych). Klucze naturalne warto więc opierać wyłącznie na polach faktycznie unikalnych, niemutowalnych i neutralnych pod względem bezpieczeństwa, np. numerach faktur, przesyłek czy kodach referencyjnych generowanych w systemie źródłowym.

Klucze naturalne w bazach relacyjnych (SQL)

W klasycznych bazach relacyjnych (SQL Server, PostgreSQL, MySQL) również spotykamy się z deterministycznymi kluczami, choć częściej mówi się o nich jako o kluczach naturalnych. Przykładami mogą być numery faktur, kody ISBN czy numery VIN. Są to pola, które jednoznacznie identyfikują rekord i nie zmieniają się w czasie.

Alternatywą są klucze techniczne (np. INT IDENTITY albo GUID), które są generowane niezależnie od logiki biznesowej. W takim podejściu zwykle dodatkowo zabezpiecza się pola biznesowe przez indeksy UNIQUE, aby zapobiec duplikatom.

W SQL wybór między kluczem naturalnym a technicznym jest głównie decyzją modelowania danych i zarządzania unikalnością, podczas gdy w Cosmos DB deterministyczne ID mają bezpośredni wpływ także na wydajność i koszt operacji (O(1) odczyty zamiast pełnych skanów partycji).

Jak tworzyć deterministyczne ID

Konkatenacja pól biznesowych

Najprostsza metoda tworzenia deterministycznych identyfikatorów to konkatenacja pól biznesowych. Identyfikator powstaje z połączenia kilku unikalnych atrybutów, np.:

public static string GetKeyOrder(string customerId, string orderNumber)
    => $"{customerId}:{orderNumber}";

Takie rozwiązanie jest wyjątkowo proste i czytelne – już po samym ID można rozpoznać, do czego się odnosi. Ma jednak i słabe strony. Długość identyfikatora zależy bezpośrednio od wartości pól, więc nie ma gwarancji stałego formatu i długości. Trzeba też uważać na separatory i sposób łączenia danych, aby uniknąć kolizji lub niejednoznaczności.

Użycie funkcji skrótu (hash function)

Drugim podejściem jest wyliczanie hasha z kluczy. Zamiast przechowywać całe wartości, można je złączyć i przepuścić przez funkcję skrótu (hash function):

public static string HashFrom(params string[] parts)
{
    using var sha = SHA256.Create();
    var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(string.Join("|", parts)));
    return Convert.ToHexString(bytes);
}

Hash ma zawsze stałą długość i nie ujawnia wprost danych biznesowych. Dzięki temu łatwiej go przechowywać, indeksować i przenosić między systemami. Jest to podejście stosowane m.in. w Git, gdzie identyfikator commita powstaje właśnie jako hash (SHA-1 lub SHA-256) obliczony z treści commita i metadanych. Dzięki temu commit o tej samej zawartości zawsze ma ten sam identyfikator, a repozytoria mogą łatwo synchronizować dane i wykrywać duplikaty. Z drugiej strony takie ID jest trudniejsze do odczytania przez człowieka, a w teorii istnieje niewielkie ryzyko kolizji.

Przy wyborze algorytmu haszowania warto brać pod uwagę nie tylko kwestie bezpieczeństwa, lecz także skalę danych. W mniejszych zbiorach wystarczą szybsze i prostsze algorytmy, które zapewniają akceptowalnie małe ryzyko kolizji. Przy dużych wolumenach danych lepiej postawić na silniejsze funkcje, takie jak SHA-256 czy SHA-512, które minimalizują ryzyko kolizji kosztem większych nakładów obliczeniowych. Algorytm musimy dobrać świadomie do charakterystyki systemu, zamiast traktować go jako rozwiązanie uniwersalne.

Podsumowanie

Deterministyczne identyfikatory nie są rozwiązaniem uniwersalnym, ale w odpowiednich scenariuszach potrafią znacząco uprościć backend. W Cosmos DB pozwalają unikać kosztownych skanów, a w systemach rozproszonych wspierają idempotencję i prostsze integracje. Dzięki temu stają się jednym z tych detali architektonicznych, które zwracają się wielokrotnie w trakcie rozwoju systemu.

Dobrze zaprojektowane ID może być różnicą między tanim odczytem a kosztownym skanem całej bazy.

Tabela wyboru sposobu nadawania kluczy w CosmosDB

W systemach opartych na zdarzeniach oraz w aplikacjach wielowątkowych często pojawia się problem nagłego wzrostu obciążenia w momencie, gdy wiele wątków jednocześnie próbuje uzyskać dostęp do tego samego zasobu. Jeśli ten jest niedostępny, każdy proces może rozpocząć kosztowną operację jego pozyskania. Zjawisko to nazywamy problemem pędzącego stada (thundering herd problem). Wszystkie jednostki wykonawcze ruszają w tym samym kierunku, a system musi zmierzyć się ze skokowym wzrostem obciążenia.

Odpowiedzią na to wyzwanie jest zastosowanie double-checked locking. Technika pozwala uniknąć równoległego odświeżania tego samego zasobu i bezpiecznie udostępnia go wszystkim potrzebującym.

Na czym polega double-checked locking

Wzorzec powstał w świecie wielowątkowego programowania jako optymalizacja dla klasycznego podejścia z blokadą. Proste użycie lock przy każdym dostępie do współdzielonego elementu jest kosztowne. Każdy wątek musi wtedy wejść do sekcji krytycznej, czyli fragmentu kodu otoczonego blokadą, do którego w danym momencie może wejść tylko jedna jednostka wykonawcza.

Double-checked locking pozwala ograniczyć ten narzut. Polega na podwójnym sprawdzaniu:

1. Poza sekcją krytyczną – sprawdzamy, czy instancja już istnieje i jest gotowa do użycia.

2. Wewnątrz sekcji krytycznej – tuż po uzyskaniu blokady sprawdzamy, czy inny wątek nie wykonał tej pracy wcześniej i wynik nie jest już gotowy.

Dzięki temu blokada używana jest wyłącznie w momencie faktycznej inicjalizacji, a nie przy każdym dostępie.

Sterownik IoT – odczyt kosztownego czujnika

Wyobraźmy sobie urządzenie pomiarowe z wbudowanym czujnikiem jakości powietrza. Każdy odczyt z sensora jest kosztowny energetycznie i zajmuje kilka sekund. W tym samym procesie działa kilka modułów (np. monitor wentylacji, logger danych, moduł alarmowy), które co pewien czas potrzebują aktualnych wartości. Gdy wszystkie naraz zauważą, że poprzednie dane się przedawniły, jednocześnie spróbują uruchomić nowy, kosztowny pomiar. Zastosowanie mechanizmu double-checked locking rozwiązuje ten problem.

Implementacja

Najpierw sprawdzamy, czy trzymany w pamięci rekord AirQualitySensorData jeszcze się nie przedawnił. Jeśli odczyt jest “świeży” zwracamy wynik bez żadnych blokad. W innym wypadku wątki przechodzą przez semafor await semaphore.WaitAsync(), który wpuszcza tylko jeden z nich na raz do sekcji krytycznej. Jeśli na wejście czeka kilka wątków i nie wystąpił błąd, to pierwszy z nich przeprowadzi odczyt z czujnika. Dlatego tuż za przejściem próbujemy po raz drugi zwrócić rekord z cache. Jeśli odczyt wciąż jest nieprawidłowy, pobieramy nowy z urządzenia, aktualizujemy cache i zwracamy wynik. Na końcu, niezależnie od wyniku czy ewentualnego wyjątku, w bloku finally wywoływane jest semaphore.Release(), aby kolejne wątki mogły wejść do sekcji krytycznej. Dzięki temu rozwiązaniu unikamy wielokrotnych równoległych odczytów z sensora, a większość wywołań kończy się szybkim zwróceniem danych z pamięci.

/// <summary>
/// Gets current air quality data, performing expensive sensor read only if necessary.
/// Uses double-checked locking with SemaphoreSlim to prevent multiple concurrent expensive operations.
/// </summary>
public async Task<AirQualitySensorData> GetCurrentDataAsync()
{
    // First check: Is cached data still valid? (no lock needed for read)
    if (cachedData?.IsValid(validityDuration) == true)
    {
        return cachedData;
    }

    // Acquire semaphore to ensure only one thread can proceed to expensive operation
    await semaphore.WaitAsync();
    try
    {
        // Second check: Re-verify data validity after acquiring semaphore
        if (cachedData?.IsValid(validityDuration) == true)
        {
            return cachedData;
        }

        // Perform the expensive sensor read operation and update cache
        cachedData = await airQualitySensor.ReadSensorAsync();

        // Return updated value
        return cachedData;
    }
    finally
    {
        // Ensure semaphore is released even if an exception occurs
        semaphore.Release();
    }
}

Mechanizmy wspierające w .NET

Nie zawsze musimy pisać kod rozwiązujący problem pędzącego stada od zera. Platforma .NET udostępnia wysokopoziomowe narzędzia z których możemy skorzystać w zależności od modelu życia obiektu.

Jednorazowa inicjalizacja operacji asynchronicznych (bez odświeżania)

Wszyscy dobrze znamy mechanizm Lazy<T>, który służy do leniwej inicjalizacji obiektu. W przypadku operacji asynchronicznych możemy użyć Lazy<Task<T>>. Podejście sprawdzi się w sytuacji, gdy nie musimy odświeżać zasobu oraz nie potrzebujemy złożonego mechanizmu obsługi błędów lub ponawiania (retry) przy inicjalizacji.

// One-time asynchronous initialization using Lazy<Task<T>>
private static readonly Lazy<Task<string>> lazyConfig = 
    new Lazy<Task<string>>(LoadConfigurationAsync);

public static Task<string> GetConfigAsync() => lazyConfig.Value;

private static async Task<string> LoadConfigurationAsync()
{
    // Simulate expensive operation
    await Task.Delay(1000);
    return "Loaded configuration";
}

Dane odświeżane/zanikające (TTL, wiele kluczy)

Jeśli dane mają określony czas życia albo potrzebujemy przechowywać ich wiele (np. kolekcję konfiguracji, pomiary z różnych czujników), wygodnie skorzystać z IMemoryCache.

Model pozwala dla pobranych zasobów ustawić między innymi:

• AbsoluteExpiration – wygaszanie wpisów po ustalonym czasie,

• SlidingExpiration – „przedłużanie życia” przy odczytach,

• priorytety i czyszczenie – system usuwa mniej istotne wpisy przy presji pamięci,

• wywołania zwrotne (callbacks) – możliwość reagowania, gdy element zostanie usunięty z cache.

Jednak IMemoryCache nie eliminuje problemu pędzącego stada. Gdy wiele wątków jednocześnie zauważy brak lub wygaśnięcie wpisu, wszystkie mogą rozpocząć kosztowną operację jego odświeżenia.
Aby tego uniknąć, musimy dalej korzystać np. z mechanizmu double-checked locking.

Dodatkowo warto pamiętać, że IMemoryCache nie jest częścią podstawowej biblioteki .NET. Sam interfejs dostępny jest w Microsoft.Extensions.Caching.Abstractions. Domyślna implementacja znajduje się w Microsoft.Extensions.Caching.Memory, którą należy dodać do aplikacji, aby używać cache w runtime.

Odczyt z IMemoryCache

if (cache.TryGetValue("sensor-data", out AirQualitySensorData data))
{
    return data;
}

Zapis do IMemoryCache z TTL

cache.Set("sensor-data", freshData, TimeSpan.FromSeconds(30));

Podsumowanie

Problem pędzącego stada (thundering herd problem) może mieć różne oblicza w zależności od typu i dostępności zasobów. W platformie .NET mamy kilka sposobów, aby go powstrzymać.

Jeśli zasób musi być utworzony tylko raz i nie wymaga odświeżania, najprostsze rozwiązanie to Lazy<Task<T>>. Mechanizm jest prosty i bezpieczny, choć ogranicza możliwości obsługi błędów.

Dla danych, które tracą aktualność i wymagają okresowego odświeżania albo gdy operacja jest bardziej złożona, dobrze sprawdza się połączenie double-checked locking z IMemoryCache. Dzięki nim kosztowne wywołanie wykonuje się jeden raz w danym okresie, a wszystkie wątki korzystają z tego samego rezultatu.

Oba podejścia skutecznie ograniczają nagłe skoki obciążenia (spikes) i pozwalają bardziej efektywnie wykorzystać zasoby naszego systemu.

Ten artykuł jest częścią serii. Przykładową implementację double-checked locking oraz inne użyteczne algorytmy przy przetwarzaniu zdarzeń znajdziesz w repozytorium: useful-async-algorithms

Systemy oparte na zdarzeniach często muszą radzić sobie z sytuacją, w której wiele procesów uruchamia się w tym samym momencie. Dzieje się tak na przykład wtedy, gdy zadania są planowane na określone godziny albo gdy klienci jednocześnie ponawiają żądania w przypadku niedostępności usługi.

Jeśli wszystkie zdarzenia wypadają w tych samych chwilach, serwer zostaje zalany falą obciążenia, tworząc gwałtowne piki (spikes). To zjawisko określa się mianem thundering herd problem.

Rozwiązaniem jest jitter – algorytm wprowadzający niewielki, losowy czas oczekiwania przed przetwarzaniem zdarzenia. Dzięki temu nacisk na system rozkłada się w czasie, a fale obciążenia przestają być groźne.

Skąd pochodzi jitter

Termin „jitter” pochodzi z telekomunikacji i oznacza zmienność opóźnienia sygnału. W transmisji danych – na przykład w rozmowie głosowej przez internet – informacje nie docierają w równych odstępach czasu. Jedna próbka dźwięku może przyjść po 20 ms, kolejna po 40 ms, a następna znowu szybciej. Dzieje się tak dlatego, że pakiety w sieci internetowej mogą iść różnymi trasami i napotykać odmienne opóźnienia. Takie zjawisko jest negatywne. Wprowadza dodatkową złożoność i pogarsza jakość transmisji.

W programowaniu jitter, wprowadzany w kontrolowany sposób jest czymś pozytywnym. Celowo implementujemy niewielkie rozchwianie czasów, by uniknąć sytuacji, w której wszystkie procesy wykonują się jednocześnie.

Redukcja skoków obciążenia w systemie monitorowania zużycia energii elektrycznej

Załóżmy, że tworzymy system monitorowania zużycia energii elektrycznej przez nasze urządzenia IoT. Nie mamy potrzeby dostarczania raportów na bieżąco. Zdecydowaliśmy, że każde urządzenie będzie wysyłać nam dane analityczne w nocy. Możemy założyć, że nasza firma odnosi sukcesy i liczba urządzeń u niezależnych klientów przekracza już 100 000. Jak rozłożyć przesyłanie danych do naszego systemu raportowania, tak by efektywnie zarządzić obciążeniem? Wprowadzenie jitter rozwiązuje ten problem.

Implementacja

Zamiast pozwalać wszystkim urządzeniom wysyłać dane dokładnie o północy, rozkładamy je na okno czasowe 00:00 – 01:00. Każde urządzenie dostaje indywidualne opóźnienie w tym przedziale.

Fixed Jitter

Idea: bazowy czas + losowa wartość z przedziału [0 - maxJitter]

/// <summary>
/// Fixed jitter that prevents server overload by spreading energy reports over time.
/// Each call waits for baseDelay plus a random amount up to maxJitter.
/// </summary>
/// <param name="baseDelay">Base wait time (always applied)</param>
/// <param name="maxJitter">Maximum additional random delay</param>
public class EnergyReportFixedJitter(TimeSpan baseDelay, TimeSpan maxJitter)
{
    private readonly TimeSpan baseDelay = baseDelay;
    private readonly TimeSpan maxJitter = maxJitter;
    private readonly Random random = new();

    /// <summary>
    /// Waits for baseDelay + random jitter (0 to maxJitter) before sending.
    /// </summary>
    public async Task SendWithJitterAsync()
    {
        var jitterMilliseconds = random.Next(0, (int)maxJitter.TotalMilliseconds);
        var totalDelay = baseDelay.Add(TimeSpan.FromMilliseconds(jitterMilliseconds));

        await Task.Delay(totalDelay);

        // Sends report now
    }
}

Percentage jitter

Idea: opóźnienie jest proporcją czasu bazowego, np. ±20%.

/// <summary>
/// Percentage jitter that prevents server overload by spreading energy reports over time.
/// Each call waits for baseDelay plus a random percentage of baseDelay.
/// </summary>
/// <param name="baseDelay">Base wait time (always applied)</param>
/// <param name="maxJitterPercentage">Maximum random percentage of baseDelay to add (0-100)</param>
public class EnergyReportPercentageJitter(TimeSpan baseDelay, int maxJitterPercentage)
{
    private readonly TimeSpan baseDelay = baseDelay;
    private readonly int maxJitterPercentage = maxJitterPercentage;
    private readonly Random random = new();

    /// <summary>
    /// Waits for baseDelay + random percentage jitter before sending.
    /// </summary>
    public async Task SendWithJitterAsync()
    {
        var jitterPercentage = random.Next(0, maxJitterPercentage + 1);
        var jitterMilliseconds = (int)(baseDelay.TotalMilliseconds * jitterPercentage / 100.0);
        var totalDelay = baseDelay.Add(TimeSpan.FromMilliseconds(jitterMilliseconds));

        await Task.Delay(totalDelay);

        // Sends report now
    }
}

Podsumowanie

Jitter to prosta, ale bardzo skuteczna technika pozwalająca uniknąć przeciążenia aplikacji w momentach skumulowanego ruchu. Zamiast pozwalać, by wszystkie zdarzenia były procesowane jednocześnie, celowo wprowadzamy niewielką losowość w harmonogramie lub czasie ponawiania. Dzięki temu serwer nie doświadcza gwałtownych pików obciążenia. Nasz system działa efektywnie, stabilnie i jego zachowanie jest przewidywalne.

Ten artykuł jest częścią serii. Przykładową implementację jitter oraz inne użyteczne algorytmy przy przetwarzaniu zdarzeń znajdziesz w repozytorium: useful-async-algorithms

Czasem w systemie zaczyna pojawiać się zbyt dużo zdarzeń. Mogą być one powtarzalne, nadmiernie szczegółowe albo po prostu nieistotne w dużej liczbie. Taka lawina informacji przeciąża nasze rozwiązanie. Potrzebujemy mechanizmu, który ograniczy częstość ich występowania. Jest nim debounce.

Skąd pochodzi debounce

Termin „debounce” pochodzi z elektroniki. Mechaniczne przyciski po naciśnięciu potrafią kilkukrotnie „odbijać” styki, generując serię krótkich impulsów zamiast jednego sygnału. Aby zapobiec błędnemu odczytowi wielu kliknięć, stosuje się układ debouncing, który czeka, aż sygnał się ustabilizuje. Ta sama koncepcja została zaadaptowana w programowaniu zdarzeń.

Redukcja powtarzalnych zdarzeń przy monitorowaniu zmian w plikach

Wyobraźmy sobie proces monitorowania zmian na dysku za pomocą FileSystemWatcher. Z jednej operacji potrafi pojawić się kilka różnych zdarzeń dotyczących tego samego zasobu. Sygnały mogą dotyczyć modyfikacji, zmiany rozmiaru, pojawienia się pliku itd. Wszystkie występują w bliskich odstępach czasowych. Reakcja na każde z nich osobno oznaczałaby kilkukrotne przeprocesowanie tych samych informacji. Zastosowanie mechanizmu debounce rozwiązuje ten problem.

Implementacja

Pełną wersję przykładu wraz z innymi algorytmami asynchronicznymi znajdziesz w repozytorium:

https://github.com/L3mur1/useful-async-algorithms

Tworząc debounce określamy tzw. debouncing window – przedział czasu, w którym kolejne zdarzenia uznajemy za duplikaty.

/// <summary>
/// Events with the same path within this time span are ignored.
/// </summary>,
private readonly TimeSpan debounceWindow;

Do podstawowej implementacji wystarczy pamiętać ostatni czas obsłużonego zdarzenia i porównać go z aktualnym. W przypadku plików musimy dodatkowo wziąć pod uwagę ścieżkę, ponieważ każde zdarzenie dotyczy innego zasobu. Dlatego używamy słownika ConcurrentDictionary, w którym trzymamy ostatni czas publikacji dla każdego zasobu osobno.

// Stores the last event time for each file path to support debouncing.
private readonly ConcurrentDictionary<string, DateTime> lastEventTimes = new();

Gdy pojawiają się kolejne sygnały, porównujemy ich czas wystąpienia z ostatnim zarejestrowanym dla danej ścieżki. Pomijamy zdarzenia, które wystąpiły wewnątrz deboucing window dla tego samego zasobu. Jeśli zdarzenie występuje poza oknem czasowym, uzupełniamy słownik i publikujemy.

/// <summary>
/// Handles incoming events and applies debouncing based on the window and path.
/// </summary>
private void OnNext(FileEvent fileEvent)
{
    if (lastEventTimes.TryGetValue(fileEvent.Path, out var lastTime))
    {
        // Check if the event is within the debounce window
        if (fileEvent.PublishTime - lastTime < debounceWindow)
        {
            // Ignore event within deboucing window
            return;
        }
    }

    // Publish event and update last event time for path
    lastEventTimes[fileEvent.Path] = fileEvent.PublishTime;
    subject.OnNext(fileEvent);
}

Warto pamiętać, że w przypadku monitorowania wielu ścieżek, np. całych folderów, słownik może rosnąć w nieskończoność i niepotrzebnie zabierać pamięć systemu. Warto wprowadzić mechanizm okresowego czyszczenia zasobów.

/// <summary>
/// lastEventTimes dictionary should be periodically cleaned up
/// to avoid memory leaks from paths that are no longer active.
/// this is example clean up
/// </summary>
private void CleanUp(long obj)
{
    var threshold = DateTime.UtcNow - debounceWindow;
    foreach (var kvp in lastEventTimes)
    {
        // Remove entries older than the threshold
        if (kvp.Value < threshold)
        {
            lastEventTimes.TryRemove(kvp.Key, out _);
        }
    }
}

Dzięki zastosowaniu debounce zamiast lawiny zdarzeń dostajemy tylko jedno – reprezentatywne dla konkretnej ścieżki – w danym oknie czasowym.

Podsumowanie

Debounce to algorytm redukujący liczbę przetwarzanych zdarzeń w systemie. Jego istotą jest powiązanie różnych sygnałów w krótkich odstępach czasu. Ma to szczególne znaczenie w przetwarzaniu zdarzeń w architekturach event-driven, które z natury są asynchroniczne i nie dają gwarancji spójności. Stosując ten wzorzec tworzymy systemy mniej hałaśliwe i bardziej oszczędne w zasobach.

Ten artykuł jest częścią serii. Przykładową implementację debounce oraz inne użyteczne algorytmy przy przetwarzaniu zdarzeń znajdziesz w repozytorium: useful-async-algorithms

Pakiet System.IO dla .NET znacznie uproszcza zarządzanie plikami. Przykładowo, pozwala kopiować je jedną linijką kodu. Działa świetnie na lokalnym dysku. Niestety, gdy plik leży na zdalnym serwerze czy network share – proste API System.IO przestaje być tylko wygodną abstrakcją i zaczyna przypominać iluzję. Ukrywa bowiem rzeczywiste wyzwania integracji między systemami.

Złożoność (complexity) schowana w System.IO

System.IO to prawdziwy triumf abstrakcji. Jeden prosty interfejs do zarządzania plikami:

string content = File.ReadAllText("dokument.txt");
File.WriteAllText("kopia.txt", content);

Pod fasadą kryje się cała masa skomplikowanych operacji których nie chcemy obsługiwać tworząc nowe rozwiązania dla biznesu. Między innymi należą do nich:

• automatyczne wykrywanie kodowania znaków,

• buforowanie danych w pamięci,

• zarządzanie uchwytami do plików (handles),

• synchronizacja dostępu między procesami.

Wszystko działa świetnie w lokalnym środowisku Windows. Iluzja pojawia się, gdy używamy System.IO z zasobami przechowywanymi w sieci. Jest to nowa złożoność, której nie da się już zaprogramować na jeden sposób za prostą fasadą. Obsługa jej wymaga dodatkowej, decyzyjnej logiki od programisty.

Iluzja System.IO w sieci

Proste API System.IO sprawia wrażenie, że operacje na plikach są zawsze przewidywalne. Jednak w przypadku zasobów sieciowych to założenie z abstrakcji szybko zamienia się w iluzję.

Podstawowe operacje na pliku

Na lokalnym dysku zapis czy odczyt zwykle są szybkie i niezawodne:

// Zapis pliku – zwykle szybka operacja lokalnie
File.WriteAllText("plik.txt", content);

Na udziale sieciowym ta sama instrukcja może trwać sekundy lub nawet minuty. Pod spodem nie ma już zapisu na lokalny dysk tylko faktyczna transmisja danych przez protokół – SMB, NFS, FTP czy inny mechanizm udostępniania plików. To one decydują o tym, czy zapis będzie atomowy, czy zerwie się w połowie, jak obsłużone będą blokady i w jaki sposób raportowane są błędy. Fasada ukrywa całą tę złożoność, dając iluzję prostoty.

Zbyt długi czas operacji

W sieci, nawet prosta operacja może zająć więcej czasu. By zabezpieczyć system przed takimi przypadkami warto użyć metod asynchronicznych. W nich można przekazać CancellationToken i w ten sposób kontrolować timeout:

// Zapis pliku metodą asynchroniczną - obsługa części problemów przez przekazanie cancellationToken
cts.CancelAfter(3500);
WriteAllTextAsync("plik.text", content, cts.CancellationToken);

Użycie async nie rozwiązuje jednak problemu zanikającego połączenia czy potrzeby ponowienia operacji.

Ponowienie i zapis pośredni

Retry w przypadku niestabilnego połączenia to standard w komunikacji HTTP – w .NET zapewnia to np. biblioteka Polly. W przypadku integracji file transfer mechanizmy ponowienia pozostają jednak w gestii programisty.

Przykładowa implementacja prostego retry:

// Przykładowa implementacja ponawiania zapisu
int retries = 3;
for (int i = 0; i < retries; i++)
{
    try
    {
        File.WriteAllText(@"\\server\plik.txt", content);
        break;
    }
    catch (IOException) when (i < retries - 1)
    {
        Thread.Sleep(1000); // prosty backoff
    }
}

Drugim częstym wyzwaniem w protokołach SMB, NFS czy FTP jest brak jednoznacznej informacji o kompletności pliku. Jeśli drugi system reaguje na pojawienie się nowego zasobu na dysku sieciowym, często robi to jeszcze przed pełnym zakończeniem zapisu i zwolnieniem pliku. Prowadzi to do wyjątków przy próbie odczytu.

Typowym rozwiązaniem jest tworzenie pliku “.done” po zakończeniu operacji lub zapis do pliku tymczasowego “.tmp“, a dopiero na koniec zmiana nazwy na docelową:

// Zapis do pliku tymczasowego
File.WriteAllText("plik.txt.tmp", content);

// Dopiero po pełnym sukcesie – zmiana nazwy na docelową
File.Move("plik.txt.tmp", "plik.txt");

Opisane sytuacje pokazują, że przy pracy z plikami w sieci to programista musi świadomie przejąć kontrolę nad logiką i rozumieć złożoność ukrytą pod fasadą System.IO.

Podsumowanie

System.IO jest świetnym przykładem siły fasady, dopóki działamy w prostym, lokalnym środowisku. Wystarczy jednak przenieść pliki do sieci, by ta wygodna abstrakcja zaczęła przypominać iluzję. Problem nie leży tak naprawdę w samej bibliotece .NET, lecz w protokołach działających pod spodem – SMB, NFS czy FTP – które próbują symulować zachowanie lokalnego dysku, choć w rzeczywistości wykonują zawodny i kosztowny transfer sieciowy. To one decydują, czy zapis potrwa dwie sekundy czy dwie minuty, czy operacja zakończy się atomowo, czy w połowie, i jak zostaną obsłużone blokady.

W takich scenariuszach deweloper musi rozumieć ukrytą złożoność: świadomie nadpisać wybory podjęte pod fasadą albo opakować kod dodatkowymi mechanizmami (retry, zapis pośredni, kontrola timeoutów). Przykład System.IO pokazuje, że żadna abstrakcja nie potrafi całkowicie ukryć działania niższych warstw. Projektując własne interfejsy warto dążyć do maksymalnego uproszczenia, ale nie kosztem decyzji, które powinny pozostać w gestii programisty. Tam, gdzie próbujemy je ukryć, zamiast mocnej abstrakcji tworzymy jedynie iluzję.

Azure Functions obiecywały wiele: skalowalność, niski koszt, zero zarządzania infrastrukturą. W teorii to idealne miejsce na wystawienie prostego API, zwłaszcza przy nieregularnym ruchu. W praktyce – funkcje nie są kompletnym frameworkiem webowym do budowy interfejsów HTTP. Tworzenie API w tym modelu często kończy się rozczarowaniem. Szczególnie teraz, gdy Microsoft porzuca stary model (in-process), a nowy (out-of-process) wprowadza poważne ograniczenia.

Dwa modele: in-process vs out-of-process

Usługa Azure Functions zadebiutowała na platformie Azure w 2016 roku jako rozwiązanie serverless, które pozwala uruchamiać małe, niezależne funkcje reagujące na zdarzenia – takie jak żądania HTTP, wiadomości z kolejki czy zdarzenia czasowe – bez potrzeby zarządzania infrastrukturą. Początkowo funkcje działały wyłącznie w modelu in-process, czyli były uruchamiane w tym samym procesie, co host Azure Functions. Pozwalało to na korzystanie z naturalnego dla programistów zestawu narzędzi ASP.NET przy budowie API – takiego samego, jak w aplikacjach OnPremises, kontenerach Docker czy Azure App Service.

Z czasem jednak ten model zaczął ujawniać swoje ograniczenia. Współdzielenie procesu z hostem oznaczało brak izolacji środowisk, trudności w aktualizacji wersji .NET, konflikty zależności oraz ograniczoną możliwość niezależnego rozwoju i testowania. Problemem była też niższa niezawodność i większe ryzyko błędów przy uruchamianiu bardziej złożonych projektów.

Aby zaadresować te wyzwania, Microsoft wprowadził w 2020 roku model out-of-process (znany również jako isolated worker). Funkcje działają tu w osobnym procesie .NET, który komunikuje się z hostem za pomocą RPC. Taka separacja pozwala używać dowolnych wersji środowiska .NET niezależnie od platformy Azure Functions i unikać konfliktów wersji.

Model isolated eliminuje wiele ograniczeń technicznych modelu in-process, ale jednocześnie rezygnuje z kilku kluczowych cech. Microsoft zdecydował, że to właśnie model out-of-process będzie jedynym wspieranym w przyszłości. Wsparcie dla Azure Functions in-process zakończy się w listopadzie 2026 roku.

Problemy modelu out-of-process w budowie API

Model out-of-process rozwiązuje pewne problemy techniczne starszego podejścia, ale w kontekście budowy API wprowadza wiele ograniczeń. Trudno je zaakceptować przy pracy nad rzeczywistymi usługami HTTP. Poniżej przedstawiam najważniejsze z nich:

Brak wsparcia dla ASP.NET

Nie można użyć UseMiddleware(), nie ma dostępu do IApplicationBuilder. Oznacza to, że nie zbuduje się automatycznie pełnego pipeline’u z autoryzacją, walidacją modeli, filtrowaniem błędów. Wszystko trzeba implementować inaczej i bardziej ręcznie. W praktyce oznacza to więcej kodu do utrzymania oraz utratę możliwości szybkiego zmianu sposobu hostowania API - gdy zdecydujesz się budowac w Isolated Model, migracja to innego środowiska będzie kosztowna.

Brak możliwości użycia najlepszych narzędzi do generowania dokumentacji API

W Azure Functions Isolated model, nie da się po prostu dodać Swashbuckle/Swagger do generowania dokumentacji jak w Web API. Potrzebna jest osobna biblioteka -Microsoft.Azure.Functions.Worker.Extensions.OpenAPI. Niestety na dzisiaj ma ona ograniczenia. Nie wspiera wielu cech ASP.NET, na przykład generowania dokumentacji dla klas powiązanych dziedziczeniem należących do kontraktu. Dodatkowo konfiguracja biblioteki jest mniej intuicyjna, a dokumentacja bywa niejasna. DX (Developer Experience) wyraźnie się pogarsza.

Cold start i niestabilna wydajność

Model out-of-process wymaga uruchomienia osobnego procesu. W planie konsumpcyjnym może to oznaczać kilkadziesiąt sekund czekania na odpowiedź po dłuższej przerwie. Co gorsza, każdy endpoint HTTP traktowany jest niezależnie – jeśli Twoje API składa się z wielu funkcji, to każda z nich ma własny cold start. W modelu in-process wystarczyło rozgrzać jeden endpoint (np. /health), by uruchomić cały proces hosta i tym samym „wybudzić” wszystkie punkty dostępowe na raz. W modelu isolated to już nie działa. Cold starty są bardziej dotkliwe i trudniejsze do obejścia. W mojej ocenie to show stopper dla większości przypadków tworzenia publicznego API.

Model in-process – umiera, ale był bardziej wygodny

Mimo swoich ograniczeń, model in-process był po prostu praktyczny dla małych API. Działał jak okrojony ASP.NET Web API – wspierał kontrolery, middleware, znane mechanizmy DI, a wiele gotowych narzędzi działało od ręki. Teraz Microsoft oficjalnie każe go porzucić. Od .NET 8 wspierany jest wyłącznie isolated worker. Jeśli korzystałeś wcześniej z in-process, będziesz musiał zaplanować migrację. Jeśli dopiero zaczynasz – warto rozważyć inne podejście do hostowania API, na przykład Azure App Service.

Flex Consumption – odpowiedź na problem cold startów w Azure Functions

Flex Consumption Plan pojawił się w Azure Functions w 2024 roku jako odpowiedź na problem cold startów. Ten model łączy zalety serverless podstawowego planu Consumption z utrzymywaniem funkcji w stanie „ciepłym” podobnie jak w planie Premium. Dzięki temu w API o nieregularnym ruchu pierwsze żądania trafiają do w pełni gotowych instancji, a ryzyko cold startu jest minimalne. Przy skalowaniu Azure korzysta z puli wstępnie przygotowanych instancji, dzięki czemu kolejne instancje uruchamiają się znacznie szybciej niż w klasycznym Consumption.

Niestety korzystanie z opcji Always Ready Instances oznacza stałe koszty – tu nie ma już darmowego miliona requestów miesięcznie, a płaci się cały czas, podobnie jak w App Service. Dodatkowo usługa nie eliminuje pozostałych ograniczeń modelu isolated.

Azure App Service – stary dobry koń roboczy

Jeśli chcesz wystawić produkcyjne REST API, nawet małe, to Azure App Service z Minimal API lub Web API moim zdaniem będzie lepszym wyborem.

Dostajesz:

• pełne wsparcie powszechnie znanego przez deweloperów środowiska ASP.NET,

• działające Swashbuckle w 3 linijki,

• middleware, DI, filtry, walidację modeli,

• przewidywalne czasy odpowiedzi i brak cold startów,

• bardzo dobre lokalne testowanie – zwłaszcza jeśli używasz kontenerów

• możliwość prostrzej migracji rozwiązania w przyszłości na inne platformy

Azure App Service daje elastyczność. Możesz uruchomić API jako zwykłą aplikację lub jako kontener – zarówno na Windowsie, jak i Linuksie.

Choć nie ma planu płatności „pay-as-you-go”, to już dziś można mieć stale działające API produkcyjne na Linuksie za ok. 45 zł miesięcznie.

Jeśli więc chcesz hostować małe API bez obaw o wydajność i przewidywalność działania – moim zdaniem Azure App Service wygrywa jakością i ergonomią z Azure Functions Isolated Model.

Jak używam Azure App Service

Sam wykorzystuję Azure App Service do hostowania mojego pet projektu - aplikacji z żartami Jokes Portal. Jest to aplikajca mobilna, która wykorzystuje Azure App Service. Działa 24/7, obsługuje realnych użytkowników i potrzebuje stabilnego API bez cold startów. Usługa sprawdza się tu znakomicie.

Podsumowanie: Nie każde rozwiązanie to API

W tym artykule skupiłem się wyłącznie na przypadku budowy REST API. Nie twierdzę, że Azure Functions są złe – wręcz przeciwnie. Model isolated to świetne narzędzie do budowy systemów event driven w chmurze Azure. Funkcje wspierają integracje z niemal wszystkimi usługami Azure out-of-the-box i doskonale sprawdzają się w scenariuszach asynchronicznych oraz transakcjach rozproszonych (Durable Functions).

Ze względu na opisane wyżej ograniczenia uważam, że Azure Functions w modelu isolated nie nadają się dziś do budowy synchronicznych REST API. W takich przypadkach warto postawić na Azure App Service. To może nie jest modne, ale po prostu działa.

Aby umożliwić im faktyczne działanie, pojawia się MCP (Model Context Protocol) — otwarty standard rozwijany przez Anthropic, który ułatwia połączenie agenta AI z otoczeniem technologicznym, w którym funkcjonuje. W dalszej części pokażę, czym jest to rozwiązanie, jak wspiera agentów AI i jak wygląda jego implementacja w .NET.

Jaki problem rozwiązuje MCP (Model Context Protocol)?

Większość współczesnych integracji AI opiera się na dostępie do publicznych interfejsów — otwartych na świat API firm trzecich (takich jak Google Drive, Dropbox, Microsoft Teams), jak również naszych własnych aplikacji, które wystawiliśmy przez HTTP. Do tego dochodzą interfejsy udostępniane przez dostawców chmurowych, które dają dostęp do zasobów takich jak pliki, funkcje, kolejki czy bazy danych. Agenci AI świetnie radzą sobie z takim środowiskiem — o ile wszystko jest wystawione i dostępne z zewnątrz.

Choć w wielu przypadkach to podejście jest wystarczające, w środowiskach enterprise — ze względu na wysokie wymagania bezpieczeństwa — to zdecydowanie za mało. Nie możemy pozwolić, by agent sztucznej inteligencji miał bezpośredni dostęp do zasobów wewnętrznych przez publiczną sieć czy zewnętrzne usługi. Potrzebujemy modelu, w którym wykonanie polecenia odbywa się wewnątrz kontrolowanej infrastruktury, bez narażania wrażliwych zasobów firmowych.

Właśnie tu pojawia się Model Context Protocol (MCP) — otwarty standard, który standaryzuje sposób, w jaki modele językowe (LLM) mogą bezpiecznie korzystać z danych i narzędzi znajdujących się w systemach wewnętrznych. Model jest już na tyle popularny, że wspierają go najważniejsze rozwiązania agentyczne, takie jak GitHub Copilot czy Claude.

Jak działa MCP (Model Context Protocol)?

MCP pozwala modelowi językowemu odwoływać się do narzędzi uruchomionych poza jego środowiskiem — np. w sieci firmowej, systemie operacyjnym użytkownika czy w prywatnej infrastrukturze.

Całość opiera się na trzech komponentach:

• MCP Host — to środowisko, w którym działa agent AI (np. Claude, GitHub Copilot). Host analizuje dostępne narzędzia (tools), które oferuje MCP Server, wybiera te dostępne w danym kontekście i decyduje, które komendy model może uruchamiać. Host potrafi też reagować na zdarzenia pochodzące z MCP Servera — protokół wspiera komunikację dwukierunkową.

• MCP Client — to komponent działający blisko modelu językowego (np. jako biblioteka w tym samym procesie). Obsługuje techniczne szczegóły protokołu — wysyła żądania do MCP Servera, odbiera odpowiedzi, monitoruje zdarzenia.

• MCP Server — to lokalna aplikacja, która działa w zaufanym środowisku (np. komputer użytkownika, serwer on-prem) i wykonuje komendy przekazane przez agenta. To właśnie tutaj odbywa się właściwe działanie — uruchamianie procesów, restart usług, czytanie plików, itd. Serwer implementuje również zabezpieczenia: ograniczenia dostępu, audyt, walidację wejścia.

  

  Schemat działania MCP: model językowy (LLM) komunikuje się z agentem (MCP Host), który deleguje polecenia do lokalnych serwerów (MCP Server) działających w zaufanym środowisku. Taka architektura umożliwia bezpieczne wykonywanie działań w systemach on-prem, bez konieczności udostępniania infrastruktury na zewnątrz.

MCP (Model Context Protocol) w środowisku .NET

W środowisku .NET możemy już dziś zacząć wdrażać MCP dzięki paczce NuGet ModelContextProtocol (link) stworzonej przez zespół Microsoftu.

Dodatkowo, na oficjalnym blogu .NET znajdziesz kompletny przykład implementacji MCP Servera w C#, z kodem źródłowym i omówieniem. Paczka jest obecnie w wersji prerelease, ale już dziś umożliwia budowanie agentów działających w wewnętrznym środowisku, z pełną kontrolą nad ich możliwościami.

Rozwiązanie DevOps do zarządzania serwerami OnPrem w oparciu o GitHub Copilot i MCP

W wielu firmach operacje DevOps w środowiskach on-prem to codzienność. Często wymagają one ręcznego logowania się na serwery, analizy logów, restartowania usług czy aktualizacji konfiguracji.

Dzięki połączeniu GitHub Copilota i MCP możemy zbudować agenta AI, który:

• działa na lokalnej infrastrukturze,

• rozumie język naturalny,

• ma dostęp do MCP Serwera,

• wykonuje polecenia (np. restart usługi, analiza logów),

• reaguje na zdarzenia (np. awaria, brak przestrzeni dyskowej),

• nie wymaga otwierania infrastruktury na zewnątrz.

Co ważne — taki agent może działać samodzielnie, wykonywać skrypty, testować scenariusze A/B czy raportować wyniki testów.

Przykładem może być wykorzystanie agenta przez inżyniera QA:

• „Ustaw feature toggle w serwisie A i zresetuj usługę na środowisku X”

• “Załóż konto klienta na serwerze A i B”

• „Sprawdź czy klient jest widoczny w bazie danych na obu środowiskach”

Przykładowy MCP Server DevOps w .NET

Przygotowałem prosty MCP Server w .NET, który działa na Windowsie i pozwala:

• listować usługi systemowe,

• zatrzymywać i uruchamiać wybrane usługi.

Repozytorium znajdziesz tutaj:

https://github.com/L3mur1/MCPDevOps

A informacje jak połączyc VS Code i Github copilot z MCP tutaj:

https://code.visualstudio.com/docs/copilot/chat/mcp-servers

Poniżej zdjęcia z rzeczywistego scenariusza, który wykonałem testowo z użyciem agenta GitHub Copilot połączonego z lokalnym MCP Serwer:

Na rozgrzewkę poprosiłem o listę wszystkich usług:

Zapytałem agenta, którą usługę można zatrzymać testowo:

Zaskoczyło mnie, jak sprawnie agent podszedł do zadania. Sprawdził status kilku usług, oceniając czy są bezpieczne do zatrzymania.

Wyłączyłem usługę, przy okazji zwróćcie uwagę na wymaganą weryfikację przy pierwszym uruchomieniu komendy:

Następnie poleciłem ponowne uruchomienie:

Nawet tak prosty MCP serwer daje możliwości z których możemy korzystać w codziennej pracy, np. do zatrzymania usług blokujących kompilacje aplikacji, czy otwarte pliki.

Wnioski

Agenci AI nie muszą ograniczać się do świata przeglądarki czy zewnętrznych API. Dzięki protokołowi MCP mogą faktycznie działać wewnątrz infrastruktury firmy — uruchamiać procesy, analizować logi, zarządzać usługami — bez narażania bezpieczeństwa i bez potrzeby tworzenia kosztownych integracji.

To otwiera zupełnie nowe scenariusze użycia, szczególnie w środowiskach o wysokim poziomie kontroli, gdzie dostęp do systemów musi być ściśle ograniczony.

Jakie zastosowania dla MCP widzicie w Waszych systemach? Czy przydałby się Wam agent AI, który restartuje usługi w środowisku, monitoruje logi albo generuje raporty po wdrożeniach?

Dajcie znać w komentarzach lub odezwijcie się do mnie bezpośrednio — chętnie porozmawiam o konkretnych pomysłach!

W zależności od rodzaju systemu, jego etapu rozwoju oraz otoczenia biznesowego, jedne charakterystyki architektoniczne mogą dominować nad pozostałymi. To właśnie je powinniśmy brać pod uwagę podczas wyboru stylu obsługi błędów. Oznacza to, że nie ma jednego słusznego rozwiązania, a wybór zależy od tego, co chcemy osiągnąć jako projekt.

W artykule przedstawię różne podejścia do zarządzania nieoczekiwanym stanem w C#, zwracając uwagę na to, jak wybory mogą wspierać wymagania niefunkcjonalne naszej aplikacji.

Wymagania niefunkcjonalne, a podejście do błędów

Resiliency (odporność)

Posłużmy się prostym systemem śledzenia przesyłek, w którym klienci sprawdzają status swoich paczek. Aby ograniczyć obciążenie systemu, dane o przesyłkach są przechowywane w cache z czasem życia ustawionym na jedną godzinę.

Jeśli podczas odświeżania pamięci podręcznej wystąpi błąd (np. przez chwilową niedostępność zewnętrznej usługi), system nie powinien przerywać działania. Zamiast tego może:

• Zwrócić wartość domyślną lub pusty wynik.

• Zarejestrować problem i użyć nieaktualnych danych.

• Podjąć próbę naprawy.

W rozwiązaniach stawiających na resiliency kluczowe jest unikanie nadmiernego używania wyjątków, co pozwala świadomie decydować o sposobie reakcji na problem i zapewnia większą elastyczność działań naprawczych.

Zamiast przerywać działanie:

throw new ExternalServiceUnavailableException();

Można zareagować w kontrolowany sposób:

if (!_shipmentApi.TryRefreshShipmentStatus(trackingId, out var shipmentStatus))
{
    return Result.Fail("Shipment status could not be refreshed.");
}

return Result.Ok(shipmentStatus);

Albo podjąć działanie naprawcze:

var cachedData = _cache.GetShipmentStatus(trackingId);
if (cachedData.IsExpired && !_shipmentApi.TryRefreshShipmentStatus(trackingId, out var shipmentStatus))
{
    Log.Warning("Failed to refresh expired shipment status. Using cached data.");
    return cachedData;
}

return shipmentStatus ?? cachedData;

Maintainability (utrzymywalność)

Pomyślmy o starym, wielki system finansowy w stadium utrzymania.

Programiści, którzy pracują przy jego łataniu, zdecydowaną większość czasu spędzają na czytaniu istniejącego kodu i szukaniu źródeł problemów. Żeby usprawnić proces, możemy:

• Weryfikować poprawność danych jak najbliżej punktu wejścia oraz jasno sygnalizować wykryte problemy.

• Jasno komunikować, dlaczego dane nie mogą zostać przetworzone.

• Udostępniać informacje, które pomogą w namierzeniu nieprawidłowości.

W legacy, zamiast pozwalać na propagację nieprawidłowego stanu i ręczną diagnostykę na podstawie wyjątków systemowych takich jak NullReferenceException w zestawieniu z ręcznie wyszukiwanymi danymi, staramy się maksymalnie uprościć szukanie przyczyny problemów.

Zamiast pozwalać na ciche błędy:

public string GetClientAddress(Guid clientId)
{
    var client = GetClientDetails(clientId);
    return client.Address;
}

Lepiej jasno i od razu sygnalizować problem:

public string GetClientAddress(Guid clientId)
{
    var client = GetClientDetails(clientId);
    if (client is null)
    throw new ClientNotFoundException($"Client details could not be retrieved. Client ID: {clientId}");

    if (string.IsNullOrWhiteSpace(client.Address))
    throw new InvalidClientDataException($"Client address is missing. Client ID: {clientId}");

    return client.Address;
}

Simplicity (prostota)

Wyobraźmy sobie szybki projekt MVP — aplikację do zamawiania kawy online, która ma jedynie sprawdzić zainteresowanie użytkowników przed rozbudową pełnej platformy.

W projekcie typu MVP lub PoC celowo rezygnujemy z rozbudowanej walidacji, koncentrując się na szybkim dostarczeniu wartości zamiast perfekcyjnej obsługi wszystkich przypadków. Jeśli coś pójdzie nie tak, aplikacja może po prostu zakończyć działanie błędem, co jest akceptowalne na tym etapie rozwoju. W takim podejściu możemy:

• Nie sprawdzać przypadków negatywnych — ewentualne błędy zostaną wykryte naturalnie przez „wykrzaczenie” systemu.

• Rzucać proste wyjątki, gdy napotkamy problem, bez tworzenia rozbudowanej hierarchii wyjątków.

Zamiast tworzyć walidację i własne wyjątki:

public Order CreateOrder(OrderRequest request)
{
    if (request == null)
    throw new InvalidOrderException("Order request is null.");

    if (request.ProductId == null)
    throw new InvalidOrderException("Product ID is missing.");

    return new Order(request.ProductId, request.Quantity);
}

Lepiej pozwolić systemowi samemu zgłosić problem:

public Order CreateOrder(OrderRequest request)
{ 
    // Brak walidacji, jeśli coś pójdzie nie tak, pojawi się naturalny wyjątek
    return _orders.First();
}

Jeśli już reagujemy, to prosto i bez zbędnych klas wyjątków:

if (!isValid)
throw new InvalidOperationException("Invalid request");

Performance (wydajność)

W .NET 9 wprowadzono istotne usprawnienia w mechanizmie obsługi wyjątków, znacząco poprawiając jego wydajność. Nowa implementacja opiera się na architekturze NativeAOT, co zauważalnie obniża koszt obsługi wyjątków, szczególnie w prostych blokach catch i podczas operacji asynchronicznych. Szczegóły tych zmian można znaleźć w oficjalnej dokumentacji Microsoft:
What's new in .NET 9 – Runtime Improvements.

Mimo tych optymalizacji wyjątki nadal przerywają przepływ wykonania, co może utrudniać optymalizację kodu i negatywnie wpływać na jego przewidywalność, zwłaszcza w sekcjach krytycznych pod względem wydajności. Dlatego w takich miejscach warto:

• Unikać wyjątków (np. w pętlach, przy parsowaniu, w przetwarzaniu równoległym).

• Stosować metody TryXXX lub prostą walidację, by zachować płynność wykonania.

Przykład do zastosowania w kodzie krytycznym wydajnościowo:

if (!decimal.TryParse(input, out var value))
return Result.Fail($"Not parsed into decimal: {input}");

Podsumowanie

Nie ma jednej, uniwersalnej strategii obsługi wyjątków — każda decyzja powinna wynikać ze świadomego wyboru, zgodnego z charakterystykami architektonicznymi systemu. Raz będzie to prostota, innym razem pełna kontrola nad poprawnością danych, a jeszcze innym — odporność systemu na nieprzewidziane sytuacje.

A Ty? Jakie podejście najczęściej stosujesz w swoich projektach?

• Pozwalasz, by wyjątki systemowe propagowały się dalej?

• Rzucasz własne wyjątki z dodatkowymi informacjami?

• Stosujesz wzorzec Result zamiast wyjątków?

• A może próbujesz automatycznie naprawiać dane i kontynuować przetwarzanie?

Czy przy wyborze sposobu obsługi błędów uwzględniasz charakterystyki architektoniczne swojego systemu?

Jakie miałem opcje? Krótki przegląd dostępnych rozwiązań

Ponieważ Jokes Portal to pierwsza aplikacja mobilna, którą rozwijam, a technologie AI rozwijają się w zawrotnym tempie, wybór odpowiedniego rozwiązania do klasyfikacji komend nie był oczywisty. Z wiedzą, którą miałem w tamtym momencie, znalazłem trzy i pół realnej możliwości wdrożenia klasyfikatora w środowisku .NET MAUI:

1. Wykorzystanie dużego modelu językowego (LLM) – np. GPT-4o mini od OpenAI, z przygotowanym promptem klasyfikacyjnym.

2. Zainstalowanie małego modelu językowego (SLM) bezpośrednio w aplikacji mobilnej, dostrojonego do komend.

   • 2.5: Osadzenie takiego samego klasyfikatora w API hostowanym na Azure

3. Użycie klasycznego rozwiązania TF-IDF (Term Frequency – Inverse Document Frequency), działającego lokalnie na telefonie użytkownika.

Czego naprawdę wymaga dobra obsługa komend głosowych?

Tworząc aplikację B2C (business to consumer), musiałem pogodzić możliwości techniczne z oczekiwaniami użytkowników. Decyzja o wyborze podejścia do klasyfikatora była podyktowana kilkoma kluczowymi czynnikami:

• Szybkość reakcji – chociaż użytkownicy są przyzwyczajeni do tego, że na rezultaty generowane przez AI trzeba chwilę poczekać, w przypadku komend oczekują działania natychmiastowego. Rozpoznawanie powinno odbywać się bez zauważalnych opóźnień, najlepiej w czasie rzeczywistym.

• Koszt operacyjny – w aplikacji konsumenckiej każde zapytanie do zewnętrznego API (np. OpenAI) generuje koszt. Co więcej, liczba komend sterujących aplikacją (np. „pokaż ulubione”, „podoba mi się”) może być znacznie większa niż zapytań, które faktycznie wyświetlają treść. To oznacza, że ich obsługa musi być jak najtańsza, aby nie wymuszać na użytkowniku oglądania większej liczby reklam.

• Możliwość działania offline – aplikacja mobilna powinna działać także przy ograniczonym dostępie do Internetu, np. w podróży. To naturalne oczekiwanie użytkowników, szczególnie w kontekście aplikacji rozrywkowej.

• Rozmiar modelu – artefakt nie może ważyć setek megabajtów, bo użytkownicy niechętnie pobierają ciężkie aplikacje. Dodatkowo, gdy zaczyna brakować miejsca w pamięci telefonu, duże aplikacje są pierwsze do usunięcia.

• Obsługa wielu języków – już na starcie aplikacja wspierała polski i angielski, więc każde rozwiązanie musiało działać równie dobrze dla obu języków. To kluczowe dla komfortu użytkownika i możliwości rozwoju aplikacji.

TF-IDF jako model ONNX

TF-IDF (Term Frequency – Inverse Document Frequency) to klasyczna technika przetwarzania języka naturalnego, która pozwala przekształcić tekst na wektor liczbowy. W tym podejściu każda komenda zostaje reprezentowana jako wektor ważonych słów, gdzie wagi odzwierciedlają znaczenie danego słowa w kontekście całego zbioru komend.

W praktyce przygotowuję zestaw reprezentatywnych komend (np. „pokaż ulubione”, „powiedz żart o zwierzętach”) i przypisuję im etykiety klas (intencji). Następnie trenuję model, który potrafi przypisać nową wypowiedź użytkownika do jednej z wcześniej zdefiniowanych intencji. Całość eksportuję do formatu ONNX, co pozwala używać tego modelu lokalnie na urządzeniu mobilnym w środowisku .Net.

Dla każdego języka (np. polski, angielski) tworzony jest oddzielny model. Przetwarzanie działa błyskawicznie (inferencja poniżej 10 ms), nie wymaga dostępu do Internetu i ma minimalny rozmiar (mniejszy niż 0.5 MB), co sprawia że można osadzić modele wewnątrz pakietu aplikacji.

Minusem rozwiązania jest to, że klasyfikator nie zwraca prawdopodobieństw – tylko etykietę intencji. Dlatego trzeba osobno zadbać o sytuację, w której użytkownik powie coś zupełnie niespodziewanego. W tym celu dodaję do zbioru treningowego specjalną klasę „unknown” z przykładami losowych, niezwiązanych komend (np. „jaka jest pogoda”, „co to jest JSON”), by model mógł nauczyć się odrzucać niepasujące zapytania.

Dodatkowym ograniczeniem TF-IDF jest brak rozumienia semantyki. Model opiera się wyłącznie na częstości występowania słów i ich wagach, bez rozpoznawania znaczenia kontekstu. Oznacza to, że rozwiązanie może mieć trudności z rozróżnieniem podobnych, ale znaczeniowo różnych komend, takich jak:

• „opowiedz losowy żart” (czyli: jakikolwiek)

• „opowiedz żart o losowości liczb” (czyli: na temat teorii prawdopodobieństwa)

Tego typu przypadki brzegowe trzeba odpowiednio obsłużyć na etapie trenowania – np. dodając więcej przykładów, które rozbijają podobnie brzmiące intencje na osobne klasy.

Small Language Model (SLM) lokalnie (ONNX)

Małe modele językowe (Small Language Models – SLM), takie jak MobileBERT, pozwalają na znacznie lepsze rozumienie kontekstu niż klasyczne podejścia oparte na słownikach. W nich trening odbywa się na przykładach komend użytkowników, a rozwiązanie wyeksportowane do formatu ONNX umożliwia lokalne uruchamianie na urządzeniu mobilnym w środowisku .Net.

SLM rozpoznaje nie tylko dokładne sformułowania, ale też różne wariacje językowe, np.:

• „powiedz coś o lekarzu”

• „opowiedz żart, w którym jest doktor”

Model działa w pełni offline, co spełnia jeden z kluczowych wymogów. Inferencja trwa zwykle 20–50 ms. Minusem tego podejścia jest rozmiar modelu co najmniej 70mb, co wpływa znacząco na wielkość paczki aplikacji. Aby zredukować ten problem, można rozważyć pobieranie modelu jako pakietu językowego na żądanie – z blob storage, który wykorzystywany jest już do dostarczania żartów w postaci audio.

W tym podejściu każdy język wymaga osobnego modelu – w moim przypadku oznacza to przetrenowanie wersji polskiej i angielskiej. W praktyce okazuje się to sporym ograniczeniem. Zdecydowana większość dostępnych modeli typu SLM została wytrenowana na języku angielskim. Dla języka polskiego istnieją modele takie jak PolBERT czy HerBERT, ale ważą one ponad 300 MB. Są zbyt ciężkie dla urządzeń mobilnych bez agresywnej optymalizacji lub ograniczania funkcji, co utrudniałoby implementację lub nawet okazało się niemożliwe do rozwiązania. Jeśli udałoby się sprostać wyzwaniom, można spodziewać się, że efekt końcowy oferuje znacznie większą odporność na przypadki brzegowe, nieoczywiste sformułowania oraz błędy rozpoznania tekstu mówionego niż TF-IDF.

Warto również wspomnieć, że modele BERT w formacie ONNX nie zawierają wbudowanej logiki tokenizacji. Przed wywołaniem modelu tekst musi zostać odpowiednio przetworzony – podzielony na tokeny zgodnie z oryginalną architekturą. W przypadku .NET można skorzystać z BertTokenizer, który jest gotowym tokenizerem zgodnym z BERT-em. To dodatkowy krok, który należy zaimplementować ręcznie przed wykonaniem inferencji.

SLM jako mikroserwis w API

Zamiast osadzać model językowy bezpośrednio w aplikacji mobilnej, można uruchomić go jako mikroserwis w API. W tym podejściu model (np. MobileBERT wytrenowany i wyeksportowany do formatu ONNX) zostaje osadzony w aplikacji serwerowej – ASP.NET Core API działającym na Azure App Service, które już teraz obsługuje backend aplikacji mobilnej. Artefakty ONNX o rozmiarze 100–200 MB, a nawet większym, mogą być bez problemu ładowane do pamięci przy starcie serwera.

Największą zaletą tego podejścia jest brak wpływu na rozmiar aplikacji mobilnej – klient nie musi pobierać dużych modeli, a przetwarzanie odbywa się po stronie backendu. Łatwiejsze jest również wersjonowanie i aktualizacja modeli – nie wymaga to publikacji nowej wersji aplikacji w Google Play.

Jeśli budżet na infrastrukturę na to pozwala, mikroserwis można uruchomić na dedykowanej instancji lub w osobnym kontenerze, co zwiększa jego skalowalność i pozwala izolować komponent odpowiedzialny za przetwarzanie języka.

W porównaniu do podejścia lokalnego tracimy możliwość działania offline. Dochodzą też koszty związane z transferem danych i utrzymaniem backendu. Zyskujemy natomiast minimalny rozmiar aplikacji oraz elastyczność zarządzania modelem.

OpenAI / GPT jako klasyfikator intencji

Podejście oparte o GPT (np. OpenAI GPT-4o mini) oferuje najwyższą jakość klasyfikacji i największą elastyczność językową. Użytkownik może powiedzieć „coś śmiesznego o lekarzach i chomikach” i model z dużym prawdopodobieństwem rozpozna kontekst i przekaże go dalej jako intencję.

Największą zaletą tego podejścia jest błyskawiczne wdrożenie – nie trzeba trenować własnego modelu, wystarczy przygotować odpowiedni prompt. Dodatkowo każde zapytanie może być logowane i analizowane, co pozwala na stopniowe zbieranie danych do późniejszego trenowania własnego rozwiązania dostrojonego do aplikacji. Z drugiej strony, zastosowanie wymaga aktywnego połączenia z Internetem, a każde wywołanie generuje koszt.

Porównanie wszystkich podejść

Poniższa tabela porównuje pięć podejść do klasyfikacji komend głosowych dla przypadku użycia w aplikacji Jokes Portal. Oceny zostały przyznane w skali od 0 (najgorzej) do 3 (najlepiej). Wartość 0 oznacza, że dane podejście w tej chwili zupełnie nie spełnia wymagań – jest "show stopperem".

Co wybrałem i dlaczego

Po porównaniu wszystkich podejść i skonfrontowaniu ich z rzeczywistymi wymaganiami aplikacji mobilnej Jokes Portal, wybór padł na klasyczny model TF-IDF wytrenowany i zapisany jako artefakt ONNX. Choć nie oferuje on zaawansowanego rozumienia języka, okazał się najbardziej opłacalny i praktyczny. Działa błyskawicznie, nie wymaga połączenia z Internetem, ma śladowy rozmiar i może być łatwo wdrażany oddzielnie dla każdego języka.

Rozwiązania oparte o modele językowe (SLM) lokalnie lub przez blob storage zapewniają większą elastyczność, ale obecnie są zbyt ciężkie (zwłaszcza dla języka polskiego). SLM jako mikroserwis był rozważany jako potencjalne rozwiązanie, jednak przegrywa z modelem dostarczanym przez blob storage pod względem kosztów, elastyczności i prostoty wdrożenia. Dodatkowo nie spełnia kluczowego wymagania działania offline. Z kolei OpenAI, mimo świetnych rezultatów i najwyższej jakości rozpoznawania języka, nie działa bez połączenia z internetem i generuje koszt przy każdym zapytaniu. W kontekście aplikacji opartej na modelu reklamowym jest to zbyt drogie do zastosowania na większą skalę.

TF-IDF (Term Frequency – Inverse Document Frequency) nie jest rozwiązaniem doskonałym, ale w połączeniu z odpowiednim zestawem treningowym spełnia wszystkie kluczowe wymagania użytkowe i techniczne. Na tym etapie rozwoju aplikacji i otaczających nas technologii uważam, że jest to po prostu najlepszy możliwy wybór.

Temat klasyfikacji komend jest innowacyjny i jak każde rozwiązania oparte o AI szybko się rozwija. Jeśli widzisz inne podejścia, masz doświadczenia z podobnymi problemami albo po prostu chcesz podyskutować, wspólnie przemyśleć podobne rozwiązanie – śmiało napisz do mnie lub zostaw komentarz.

Jako praktyczny przykład prezentuję schemat architektoniczny mojej aplikacji mobilnej JokesPortal, w której często spotykam się z koniecznością łączenia danych z różnych źródeł - systemów przechowywania i produktów 3rd party:

Podczas łączenia dużych zbiorów danych łatwo przeoczyć jedno z najczęstszych źródeł utraty wydajności – wielokrotne wyszukiwanie elementów jednej kolekcji w drugiej.

W artykule pokażę jak skutecznie wykonywać agregację elementów między kolekcjami w warstwie obliczeniowej. Podzielę się z Tobą obrazową analogią oraz praktycznym, krótkim benchmarkiem.

Analogia dostawcy jedzenia

Wyobraź sobie, że pracujesz jako dostawca jedzenia w znanej firmie, w której najczęściej Twoim pojazdem służbowym jest rower elektryczny lub skuter. Masz do dostarczenia pełną torbę zamówień do największego bloku w mieście - 10 000 mieszkań.

W swojej aplikacji mobilnej widzisz wszystkie potrzebne informacje, w tym numery lokali pod którymi głodni klienci czekają na dostawę. Gdy wchodzisz do budynku, czeka na Ciebie przykra niespodzianka. Blok jest na tyle nowy, że zarządca nie umieścił jeszcze numerów mieszkań na drzwiach i korytarzach.

Aby dostarczyć zamówienie, musisz pukać do każdych drzwi pytając o numer lokalu i porównując go z odpowiednikami na opakowaniach, które masz w torbie. Jesteś zbyt zabiegany, by choćby posortować paczki z jedzeniem.

Ta niewesoła sytuacja jest dokładnym odpowiednikiem wywoływania metody .Contains() na liście w każdej iteracji pętli. Każdorazowo przeszukujesz torbę z jedzeniem w poszukiwaniu konkretnego numeru zamówienia. Czynność powtarzasz dla każdych drzwi w bloku.

Optymalne rozwiązanie: użycie HashSet lub Dictionary.

Z reguły mieszkania w budynku są oznaczone numerami. Dodatkowo, na każdym piętrze, a może przy wejściu do budynku może znajdować się lista z rozpiską: piętro - numery mieszkań. Dzięki temu możesz skierować się od razu do właściwego mieszkania.

Jeśli kilka zamówień trafia pod jeden adres lub na to samo piętro, warto na chwilę zatrzymać się przy tablicy z numerami mieszkań i uporządkować torbę. Może to zaoszczędzić sporo czasu.

W .Net analogiczną, właściwą optymalizację dla takiego przypadku użycia oferują struktury danych takie jak HashSet lub Dictionary. Korzystają one z indeksu na podstawie hashów. Umożliwiają błyskawiczny dostęp i eliminują konieczność niepotrzebnego przeszukiwania całych kolekcji. Dodatkowo, algorytmy oparte na indeksach gwarantują stały czas wyszukiwania, w przeciwieństwie do wyszukiwania liniowego, które może się znacznie różnić w zależności od rozkładu danych.

Benchmark metod .Contains() i .Select()

Aby pokazać różnice wydajności pomiędzy różnymi podejściami do wyszukiwania wielu elementów w kolekcjach, przygotowałem praktyczny benchmark. Porównałem kilka metod, które często stosujemy w aplikacjach .NET. Poniżej przedstawiam wyniki tych pomiarów. Eksperyment przeprowadziłem w środowisku .Net9.

Kod źródłowy dostępny na moim GitHub.

Konfiguracja

Porównałem kilka typowych scenariuszy wyszukiwania w celu zmierzenia wydajności wyszukiwania wielu elementów w kolekcji:

Wyniki

Poniżej przedstawiam wyniki benchmarku wyszukiwania 1000 elementów w kolekcji liczącej 10 000 elementów (środowisko .NET 9):

Przedstawione wyniki dotyczą konkretnego przypadku testowego – w praktyce warto powtórzyć benchmarki, dostosowując rozmiary kolekcji do własnych potrzeb.

Wnioski

Benchmark wyraźnie pokazuje, że przy wielokrotnych wyszukiwaniach warto przekształcić kolekcję do Dictionary lub HashSet. Należy unikać .Contains() i innych operacji liniowych na listach w pętlach.

Na liczbach

Przy potrzebie pojedynczej iteracji przez kolekcję, zamiana na słownik (Contains_Multiple_Dictionary) daje wzrost wydajności o ~14x w stosunku do korzystania z listy (Contains_Multiple_List_Any).

374.165 / 245.24​ = 14.02 ~ 1 400%

Gdy wymagane jest kilka przejść przez pętlę, wydajność Precomputed Dictionary sprawia, że kolejne przejścia nie mają istotnego wpływu na redukcję wydajności, każde kolejne wyszukiwanie jest ~365x szybsze w porównaniu do użycia listy Contains_Multiple_List_Any

5245.24​ / 14.35 = 365.52 ~ 36 500%

Przykład, jak skutecznie wyszukać wiele elementów w liście.

To przykład zamiany listy w słownik przy wyszukiwaniu elementów o takim samym ID(Guid) ze stworzonych benchmarków:

Uwaga

Metoda .ToDictionary() wymaga unikalnych kluczy – w przypadku duplikatów rzucony zostanie wyjątek ArgumentException. Jeśli dane pochodzą z wielu źródeł, a duplikaty są możliwe, warto najpierw je obsłużyć (np. używając .GroupBy().ToDictionary()).

Dodatkowe informacje

Warto również pamiętać także o metodach LINQ, takich jak .Intersect() czy .Except(), które także wykorzystują haszowanie.

Jak przetestować generator struktury XML?

Podczas pracy nad kodem źródłowym do tworzenia tekstu dla efektywnej syntezy mowy, zauważyłem, że większość interfejsów, czyli całe „mięso”, to w istocie tworzenie generatorów odpowiedniej struktury XML, którą jest SSML. Zacząłem zastanawiać się, jak przetestować poszczególne bloki struktury, które sprowadzały się praktycznie do implementacji poniższego interfejsu:

 public interface ISsmlElement
    {
        /// <summary>
        /// Converts the implementing element to an SSML-formatted element.
        /// </summary>
        /// <param name="ns">The XML namespace to be used for the SSML element, if needed.</param>
        /// <returns>An <see cref="SsmlElement"/> that represents the current object in SSML format.</returns>
        SsmlElement ToSsml(XNamespace? ns = null);
    }

czyli w praktyce zwrócenia obiektu XML:

public class SsmlElement
    {
        [...]
        /// <summary>
        /// Gets the underlying XElement representation of this SSML element.
        /// </summary>
        public XElement XElement { get; }
        [...]
    }

Asserty XElement

Pierwszym pomysłem, a tak naprawdę brakiem zrozumienia problemu, byłoby każdorazowe przygotowywanie oczekiwanego obiektu XML do porównania w assercie. W czasach GPT możemy łatwo „wyobrazić” sobie, jakby wyglądałyby Asserty w tej sytuacji i jakie byłoby ich setupowanie:

// give me c# code that will produce such content hardcoded, using XElements: [...]
XNamespace ns = "http://www.w3.org/2001/10/synthesis";
        XElement expectedElement = new XElement(ns + "speak",
            new XAttribute("version", "1.0"),
            new XAttribute(XNamespace.Xml + "lang", "en-US"),
            new XElement(ns + "voice",
                new XAttribute("name", "en-US-AvaMultilingualNeural"),
                "Why are snails slow?"
            )
        );

Utrzymanie tego rodzaju testów z pewnością nie jest przyjemne, a błędy w literkach mogą prowadzić do kolejnych straconych minut. Co więcej, jak sprawdzić, czy Azure Speech Service zgodnie z oczekiwaniem interpretuje ten skomplikowany markup? Wydaje się, że nie obyłoby się bez testów integracyjnych, ale takie rozwiązanie rodzi tylko kolejne pytania bez odpowiedzi. Jak przetestować nagranie dźwiękowe? Jak uruchamiać testy integracyjne przeciwko chmurze Azure w projekcie, który stworzyłem jako open source? To totalna przesada w kontekście utrzymania.

Może testować plain text?

Jeśli Pomysł na Asserty XElement nie wchodzi w grę, mam pomysł by porównywać rezultat generowania jako plain text. Zgodnie z dokumentacją metody XNode.ToString(), która zwraca XML dla reprezentowanego przez obiekt węzła, można użyć tej metody do generowania i porównywania stringów XML. Oto przykład takiego rozwiązania:

// Arrange
            var sut = Speak.InLanguage("en-US")
                .WithElement(Voice
                .Named("en-US-AvaMultilingualNeural")
                .WithContent(Content.Of("Why are snails slow?")));

            // Act
            var result = sut.ToString();

Do assercji można przygotować zahardkodowany string z oczekiwaną strukturą XML. To rozwiązanie jest lepsze, ponieważ programista widząc oczekiwaną strukturę:

var expectedResult = "<speak version="1.0" xml:lang="en-US" xmlns="http://www.w3.org/2001/10/synthesis">
  <voice name="en-US-AvaMultilingualNeural">Why are snails slow?</voice>
</speak>"

ma możliwość wizualnej oceny struktury XML, co daje lepsze zrozumienie tego, czego dotyczy test, a także umożliwia łatwe skopiowanie wyniku lub oczekiwanego rezultatu do Azure Speech Studio i przesłuchania wygenerowanego nagrania. Skopiowanie struktury z debuggera Visual Studio zamienia znaki „<“ na „lt” ze względu na zabezpieczenie przed atakami typu injection, ale to problem można rozwiązać w dalszej pracy nad kodem. Kolejne dopracowanie tego pomysłu polega na zastąpieniu oczekiwanych rezultatów, hardkodowanych w postaci stringów elementów XML, przechowywaniem ich w osobnych plikach. Dla każdego testu można by mieć oddzielny plik XML, co ułatwi zarządzanie i aktualizację oczekiwanych wyników bez potrzeby ingerowania w kod źródłowy testów. To podejście znacząco usprawnia zarządzanie testami i może przyczynić się do lepszej organizacji oraz czytelności testów. Należałoby przygotować po jednym pliku dla każdego przypadku testowego. Czy istnieje lepszy sposób?

Testowanie przeciwko Snapshotom

Co to jest Snapshot testing?

Snapshot testing, czyli testowanie migawek, to technika oprogramowania, która polega na porównywaniu aktualnego stanu obiektu z wcześniej zapisanym „zrzutem”. Automatyzacja procesu zapisywania i porównywania snapshotów jest często zapewniana przez różne SDK. Ta metoda jest szczególnie popularna w testowaniu interfejsów użytkownika, gdzie zmiany są zazwyczaj subtelne, aby nie wprowadzać zamieszania i utrzymać komfort użytkowania. Interfejsy użytkownika, takie jak HTML czy XAML, ze względu na ich względną stabilność, są idealnymi kandydatami do tego rodzaju testowania.

Rozwój AI otwiera nowe możliwości dla technik testowania migawek, szczególnie w kontekście analizy i interpretacji obrazów. Narzędzia takie jak Analiza obrazu w usługach Azure mogą przyczynić się do rozwijania nowych metodologii testowania, które będą w stanie lepiej rozumieć i interpretować zmiany wizualne. To może obejmować nie tylko tradycyjne snapshoty, ale również bardziej zaawansowane formy oceny zmian w dynamicznie generowanych interfejsach czy wizualnych aspektach aplikacji. Możliwość automatycznego rozpoznawania i oceniania zmian wizualnych dzięki AI może znacząco zwiększyć efektywność i dokładność procesów testowych, zmieniając sposób, w jaki podchodzimy do zapewnienia jakości w rozwoju oprogramowania.

Testowanie generowanych XML ze snapshotów - Verify

Wystarczyło połączyć kilka elementów, aby uzyskać rozwiązanie, które jest szybkie w implementacji i proste w utrzymaniu. Verify to biblioteka dla platformy .Net, umożliwiająca tworzenie testów typu snapshot. Po jej wdrożeniu cały proces testowania sprowadził się do generowania struktur i wywoływania weryfikacji, na przykład w SpeakTests:

[Fact()]
        public async Task WhenElement()
        {
            // Arrange
            var sut = Speak.InLanguage("en-US")
                .WithElement(Voice
                .Named("en-US-AvaMultilingualNeural")
                .WithContent(Content.Of("Why are snails slow?")));

            // Act
            var result = sut.ToString();

            // Assert
            await Verify(result);
        }

W wyniku pierwszego uruchomienia testu został wygenerowany snapshot w postaci pliku .txt, który można było nagrać i sprawdzić w Azure Speech Studio, a następnie zapisać w systemie kontroli wersji jako oczekiwany rezultat dla kolejnych wykonania. To przykład rezultatu dla testu powyżej:

<speak version="1.0" xml:lang="en-US" xmlns="http://www.w3.org/2001/10/synthesis">
  <voice name="en-US-AvaMultilingualNeural">Why are snails slow?</voice>
</speak>

Warto dodać, że biblioteka Verify w ciekawy sposób obsługuje testy wyjątków, traktując je tak samo jak każdy inny wynik, czyli generując snapshot oczekiwanego stanu. To przykład rezultatu dla wyjątku:

{
  Type: SsmlBuilderException,
  Message: No speak elements.,
  StackTrace: at SSMLBuilder.Azure.Elements.Speak.ToSsml()
}

Snapshot testing w pracy nad bibliotekami i open source

Tworzenie SDK, w formie bibliotek, opiera się na podobnych zasadach jak tworzenie interfejsów użytkownika. W tym przypadku naszym klientem jest deweloper korzystający z naszego API, a nie końcowy użytkownik. Dbamy o jego komfort, utrzymując stabilne interfejsy, których drastyczne zmiany mogłyby wprowadzić chaos i zakłócić działanie procesów opartych na naszym rozwiązaniu.

Pracując nad projektami open source, umożliwiamy innym wgląd w nasz kod oraz jego ewentualną modyfikację. Z jednej strony otwiera to ogromne możliwości dzięki połączeniu umiejętności programistów nie tylko z naszej firmy. Z drugiej strony, tworzymy bardziej uniwersalne rozwiązania, które mogą zaspokoić potrzeby nie tylko naszego biznesu, ale potencjalnie całego świata. Wykorzystanie naszej biblioteki w branżach takich jak medycyna czy finanse wiąże się z większą odpowiedzialnością. Wprowadzanie zmian w kodzie przez innych programistów wymaga zaufania oraz weryfikacji, aby upewnić się, że nie wprowadzą one błędów do SDK.

Dzięki zastosowaniu testów migawkowych, umożliwiamy sprawdzanie poprawności działania kodu bez dogłębnej znajomości domeny. Przy proponowaniu zmian, całe community zaangażowane w tworzenie open source może zobaczyć, jak zmienią się rezultaty poszczególnych wywołań oraz zachowanie nowych interfejsów. Przechowywanie snapshotów w ogólnodostępnej bazie kodu pozwala programistom, czyli użytkownikom, na dostęp do migawek, które w połączeniu z testami można traktować jako dokumentację sterowaną zachowaniem. Dodatkowo, w przypadku błędów, mogą przeszukać naszą bazę kodu w poszukiwaniu odpowiedzi na pytanie, jaki scenariusz prowadzi do wywołania konkretnego wyjątku.

Kiedy używać snapshot testing?

Snapshot testing jest potężnym narzędziem, szczególnie wartościowym w kilku kluczowych scenariuszach:

1. Sprawdzanie regresji w rozwiązaniach opartych na generatywnej sztucznej inteligencji: Testy migawek umożliwiają szybkie wykrycie i dokumentowanie niepożądanych zmian oraz ocenę jakościową, ludzkim okiem, generowanych przez GPT rozwiązań.

2. Testowanie skomplikowanych struktur danych: Idealne do zapisywania i porównywania złożonych struktur, takich jak dokumenty czy wykresy, z oczekiwanymi wynikami, co zapewnia precyzyjne sprawdzanie zgodności.

3. Wizualna weryfikacja rezultatów: Gdy zależy nam na szczegółowym sprawdzeniu formatowania lub wyglądu interfejsów, snapshot testing pozwala na dokładne uchwycenie i porównanie stanu wizualnego elementów, z dokładnością do whitespace.

4. Dokumentacja struktur danych: Testy migawkowe mogą służyć jako narzędzie dokumentacyjne, umożliwiające precyzyjne śledzenie i kontrolę sposobu przekazywania danych między różnymi częściami systemu. W przypadku tworzenia rozwiązań open source, jak SSMLBuilder.Azure dla platformy Azure, snapshoty tworzą dokumentację, która jest zarówno precyzyjna, jak i łatwa do aktualizacji.

Stosowanie testów migawkowych zapewnia solidne zabezpieczenie przed niekontrolowaną regresją i daje możliwość wzrokowego zastanowienia się nad wprowadzanymi zmianami do kontraktów. Z zainteresowaniem obserwuję, jak dynamicznie rozwijająca się branża przetwarzania obrazów oraz rosnące potrzeby weryfikacji modeli AI przeciwko regresji wpłyną na rozwój tego rodzaju narzędzi.