AI General Knowledge Handbook

on Sep 6, 2026, tagged translations, ai, openai, mcp, ai-skills, rag, tooling (share this post, e.g., on Mastodon or on Bluesky)

This article is a long-term–maintained knowledge handbook for “AI General Knowledge,” focusing on foundational, universal, and stable specifications and protocols—including the OpenAI API protocol, the MCP format specification, the SKILL format specification, RAG knowledge bases, Spring AI, and more. It is continuously updated as technology evolves and serves as a unified reference and fallback for the series of articles that follow.

1. Basic Concepts

2. The OpenAI API Protocol

1. Protocol Overview

The OpenAI API adopts a RESTful + JSON style, completing model calls via HTTP requests. The current core consists of two types:

• Chat Completions API: /v1/chat/completions, general conversation and tool calling
• Responses API: /v1/responses, the next-generation unified interface, planned to gradually replace the former

Due to its de facto standard status, many open-source models and local inference frameworks—DeepSeek, Qwen (DashScope compatibility mode), Ollama, vLLM, and others—provide “OpenAI-compatible” endpoints, and client code can generally be switched seamlessly (only the Base URL and model name need to be changed).

2. Request and Message Structure

Request core fields:

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "You are a capable assistant" },
    { "role": "user", "content": "How's the weather in Xi'an today?" }
  ],
  "temperature": 0.7,
  "stream": false
}

Role (message roles):

3. Streaming/SSE

With stream: true enabled, the server returns increments piece by piece using Server-Sent Events; each chunk is a single line data: {…}, and when finished it sends data: [DONE]:

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"X"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"i"},"finish_reason":null}]}

data: {"id":"chatcmpl-xxx","choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

Non-streaming response core fields: choices[].message.content (output text), choices[].message.tool_calls (tool calls), choices[].finish_reason (stop / length / tool_calls, etc.), usage (prompt_tokens / completion_tokens / total_tokens).

4. Function Calling (Tool Calling)

By declaring tools, the model autonomously decides when to call them; two rounds work together:

Round 1: Declare the tools and send the request. The model returns structured tool_calls instead of a direct answer:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "How's the weather in Beijing?" }],
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get the weather forecast by city name",
      "parameters": {
        "type": "object",
        "properties": { "city": { "type": "string", "description": "City name" } },
        "required": ["city"]
      }
    }
  }]
}

Example response (illustrative):

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": { "name": "get_weather", "arguments": "{\"city\":\"Beijing\"}" }
      }]
    }
  }]
}

Round 2: Feed back the execution result. Append the result as a message with role: "tool" and a tool_call_id; the model then generates the final answer:

{
  "messages": [
    { "role": "user", "content": "How's the weather in Beijing?" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [{ "id": "call_abc123", "type": "function", "function": { "name": "get_weather", "arguments": "{\"city\":\"Beijing\"}" } }]
    },
    { "role": "tool", "tool_call_id": "call_abc123", "content": "Light rain, 18°C" }
  ]
}

5. Structured Output

Constrain output to strictly conform to a JSON Schema via response_format:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "Summarize the following content into a card: …" }],
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "summary_card",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "points": { "type": "array", "items": { "type": "string" } }
        },
        "required": ["title", "points"],
        "additionalProperties": false
      }
    }
  }
}

6. Embedding and Other Capabilities

• Embedding: POST /v1/embeddings, with input + model parameters, returns a vector array, used for semantic retrieval and clustering
• Images: text-to-image (images/generations), image understanding (multimodal input)
• TTS/STT: speech synthesis and transcription
• Realtime API: low-latency voice conversation based on WebSocket

7. Minimal Call Example (Generic Across Compatible Endpoints)

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

from openai import OpenAI

client = OpenAI(base_url="https://api.openai.com/v1", api_key="sk-xxx")
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Tell me a cold joke"}],
)
print(resp.choices[0].message.content)

When switching to DeepSeek/Qwen/Ollama/vLLM and other compatible services, you only need to replace base_url (e.g., https://api.deepseek.com, http://localhost:11434/v1) and model; the SDK requires no changes.

3. The MCP Format Specification (Model Context Protocol)

1. Positioning and Architecture

MCP (Model Context Protocol) is an open protocol—like the “USB-C” of the AI field—that unifies how LLM applications connect to external data sources, tools, and services, decoupled from any specific model. Core components:

• Host: The AI application that expects to obtain capabilities from a server (IDEs, chat clients, etc.)
• Client: A connection proxy in one-to-one correspondence with a server, responsible for negotiation and message routing
• Server: A lightweight program that exposes capabilities as tools, resources, and prompt templates
• Base protocol: Defines the message format, lifecycle, and transport mechanisms

2. Message Format and Lifecycle

MCP messages are based on JSON-RPC 2.0: requests (request/response) and notifications. The protocol handshake must complete in order: initialize → notify initialized (notifications/initialized) → runtime capability calls → close.

Typical runtime methods:

• tools/list: Get the list of tools exposed by the server and their input JSON Schemas
• tools/call: Invoke a specified tool
• resources/list/resources/read: Expose and read data resources
• prompts/list/prompts/get: Expose reusable prompt templates

3. Transport Methods

4. Client Configuration Format

Mainstream clients (Cherry Studio, Claude Desktop, Cline, OpenCode, etc.) use the following JSON to declare MCP services:

{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": ["-y", "@some/mcp-weather"],
      "env": { "API_KEY": "xxx" }
    }
  }
}

Remote HTTP services can also use a URL:

{
  "mcpServers": {
    "remote": { "url": "https://mcp.example.com/mcp" }
  }
}

For detailed practice (developing an MCP Server with Spring AI and integrating it with Qwen), see the site's “Implementing an MCP Service with Spring AI and Integrating It with Qwen”.

4. The SKILL Format Specification

1. Positioning and Structure

A skill is a lightweight, reusable “capability package” that encapsulates instructions, steps, examples, and caveats for a specific task in Markdown, for an AI to discover and load on demand. The common directory convention is: a skill marketplace or .agents/skills/<skill-name>/ within a project, with SKILL.md as the main entry point.

.agents/skills/
└── <skill-name>/
    ├── SKILL.md      # Main instructions: frontmatter metadata + usage guide
    └── …           # Optional: references/ material, scripts/ scripts, examples, etc.

2. Frontmatter Metadata (Example)

---
name: weather-query
description: Query real-time weather by city name. Use when the user asks about the weather.
version: 1.0.0
metadata:
  author: xxl
  license: MIT
---

Field requirements: name must be unique and descriptive; description concisely states the functionality and trigger scenarios (the AI relies on it for skill matching—it should include trigger keywords and boundaries); add version and the like as needed.

3. Ecosystem Variants

Hands-on practice: “Extending AI Capabilities: An npx Skills Handbook” and “Open-Source AI Agent: The Principles and Practice of Integrating OMO with OpenCode”.

4. Writing Best Practices

• ✅ Focus on a single purpose: one Skill does one thing
• ✅ The description states trigger conditions and limits, enabling automatic discovery
• ✅ Steps are minimally executable, with explicit example inputs and outputs
• ✅ Manage version and compatible agents with frontmatter, enabling evolution and traceability

5. Knowledge Bases (RAG)

1. The RAG Pipeline

RAG (Retrieval-Augmented Generation) is the general paradigm for private-domain and real-time knowledge Q&A. The core pipeline:

1. Document parsing: Convert PDFs, Word documents, web pages, etc. into plain text and clean out invalid content
2. Chunking: Split by paragraph, semantics, or a fixed window, balancing intra-chunk semantic integrity with inter-chunk overlap
3. Embedding: Convert chunked text into vectors and store them in the database
4. Retrieval: Vectorize the query and recall the Top-K by similarity
5. Augmented injection: Splice the recalled fragments into the prompt, hand them to the LLM for generation, and annotate the citation sources

2. Retrieval Optimization

• Hybrid retrieval: Fuse vector recall with keyword (BM25) recall, balancing semantics with exact word matching
• Rerank: Fine-rank the recalled candidates to improve Top-K hit quality
• Graph enhancement (GraphRAG): Build entity-relation graphs to support multi-hop reasoning and global questions
• Citation tracing: Outputs carry source fragments for verification and trust

3. Vector Database Selection

Hands-on practice: “Building a RAG Knowledge Base with Milvus and Ollama”.

6. Spring AI

1. Ecosystem Positioning

Spring AI is Spring's official AI application framework, providing unified abstractions for the Java ecosystem: multi-vendor model access, structured output, function calling, RAG (Embedding + Vector Store), and MCP (official Java SDK implementation). It integrates AI capabilities into Spring applications in a bean-based, declarative way.

2. Maven Dependencies

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>1.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-model-openai</artifactId>
</dependency>

3. Minimal Call Example

@RestController
public class ChatController {

    private final ChatClient chatClient;

    public ChatController(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    @GetMapping("/chat")
    public String chat(@RequestParam String msg) {
        return chatClient.prompt(msg).call().content();
    }
}

spring:
  ai:
    openai:
      base-url: https://api.openai.com
      api-key: ${OPENAI_API_KEY}
      chat:
        options:
          model: gpt-4o

4. Tool Function Calling and MCP

• @Tool/@ToolParam annotations declare tool methods; ToolCallbackProvider registers them
• spring-ai-starter-mcp-server-* quickly builds an MCP Server (stdio/WebMvc)
• McpClient connects to remote MCP Servers synchronously or asynchronously, for use as ChatClient tools

@Service
public class WeatherService {

    @Tool(description = "Get the weather forecast by city name")
    public String getWeatherByCity(@ToolParam(description = "City name") String city) {
        return Map.of("Xi'an", "Sunny", "Beijing", "Light rain")
                .getOrDefault(city, "No data found for this city");
    }
}

@Bean
ToolCallbackProvider weatherTools(WeatherService weatherService) {
    return MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
}

For detailed implementation, see “Implementing an MCP Service with Spring AI and Integrating It with Qwen”.

7. Appendix

1. Changelog

2. Related Articles on This Site

• Implementing an MCP Service With Spring AI and Integrating It With Qwen
• Extending AI Capabilities: An npx Skills Handbook
• Building a RAG Knowledge Base With Milvus and Ollama
• Spec-Driven AI Programming: From the SDD Concept to Spec-Kit Practice
• Open-Source AI Agent: The Principles and Practice of Integrating OMO With OpenCode
• An AI Paradigm Shift: Using the XXL-BOOT SKILL to Generate Business Applications From a Single Sentence

3. Official References

1. platform.openai.com/docs/api-reference
2. modelcontextprotocol.io
3. docs.claude.com/en/docs/agents-and-tools/agent-skills
4. docs.spring.io/spring-ai/reference
5. github.com/spring-projects/spring-ai-examples

(This post is a machine-made, human-reviewed, and authorized translation of xuxueli.com/­blog/­?blog=ai/­ai-knowledge.)