> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Markdown 文件

> 在对话和 API 调用中使用 Markdown 文件作为文本上下文，分析 README、文档、笔记和变更记录。

Markdown 文件适合处理 README、接口文档、项目说明、会议纪要、知识库条目和变更记录。Moxus AI 当前支持在“对话”中上传 `.md` 与 `.markdown` 文件；接口调用时，将 Markdown 正文作为文本放入消息内容即可。

## 支持方式

<Columns cols={2}>
  <Card title="对话上传" icon="message-square">
    在“对话”输入框上传 `.md` 或 `.markdown` 文件。系统会读取文件文本，并随本次消息一起发送给模型。
  </Card>

  <Card title="接口调用" icon="code-xml">
    在服务端读取 Markdown 文件内容，将其拼入 `messages.content`。模型会把它作为普通文本上下文处理。
  </Card>
</Columns>

## 文件规则

| 项      | 说明                  |
| ------ | ------------------- |
| 支持格式   | `.md`、`.markdown`   |
| 内容类型   | `text/markdown`     |
| 单个文件大小 | 对话上传上限约 20MB        |
| 计费方式   | 按实际进入请求的文本 Token 计费 |
| 适合模型   | 支持长文本理解的对话或推理模型     |

Markdown 文件不会像图片一样作为 `image_url` 传入，也不会像 PDF 一样作为文件对象传入。它会被读取成文本，并追加到用户消息中。

## 对话中使用

<Steps>
  <Step title="打开对话">
    登录后进入“对话”页面，选择一个适合长文本分析的模型。
  </Step>

  <Step title="上传 Markdown 文件">
    点击输入框左侧的附件按钮，选择 `.md` 或 `.markdown` 文件。文件会显示在消息附件区域。
  </Step>

  <Step title="写清楚任务">
    在输入框说明你希望模型做什么，例如总结文档、提取接口列表、检查变更风险或改写说明。
  </Step>

  <Step title="发送并查看结果">
    Markdown 内容会随消息一起发送。发送后可在“控制台与用量”查看本次请求记录和消耗。
  </Step>
</Steps>

## API 调用示例

接口调用时，先在你的程序中读取 Markdown 文件，再把正文放入 `messages.content`。将 Markdown 文件放在项目根目录（即保存 `.py` 或 `.mjs` 代码文件、并从该目录运行命令的文件夹）中。代码里的 `MARKDOWN_PATH = "README.md"` 就是要读取的文件名：你的文件叫 `notes.md` 时，直接改成 `MARKDOWN_PATH = "notes.md"`。文件名、扩展名和大小写必须与实际文件一致；文件不在项目根目录时，填写它的完整本地路径。无需单独上传 Markdown 文件，代码会读取其文本并随请求发送。

Python 示例需要先安装 SDK：

<CodeGroup>
  ```bash macOS / Linux theme={null}
  python3 -m pip install openai
  ```

  ```powershell Windows theme={null}
  py -m pip install openai
  ```
</CodeGroup>

Node.js 示例在 `npm` 与 `pnpm` 中任选一种。Windows 中若 `py` 不可用，Python 依赖命令改为 `python -m pip install openai`。

<CodeGroup>
  ```bash npm theme={null}
  npm install openai
  ```

  ```bash pnpm theme={null}
  pnpm add openai
  ```
</CodeGroup>

<CodeGroup>
  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="你的密钥",
      base_url="https://moxus.cloud/v1",
  )

  MARKDOWN_PATH = "README.md"  # 项目根目录中的 Markdown 文件名；替换为你的实际文件名。

  with open(MARKDOWN_PATH, "r", encoding="utf-8") as file:
      markdown = file.read()

  response = client.chat.completions.create(
      model="gpt-5.4-mini",
      messages=[
          {
              "role": "user",
              "content": f"请总结下面这个 Markdown 文件，并列出关键功能：\n\nMarkdown file: {MARKDOWN_PATH}\n\n{markdown}",
          }
      ],
  )

  print(response.choices[0].message.content)
  ```

  ```javascript Node.js theme={null}
  import OpenAI from "openai";
  import { readFileSync } from "node:fs";

  const client = new OpenAI({
    apiKey: "你的密钥",
    baseURL: "https://moxus.cloud/v1",
  });

  // 项目根目录中的 Markdown 文件名；替换为你的实际文件名。
  const MARKDOWN_PATH = "README.md";
  const markdown = readFileSync(MARKDOWN_PATH, "utf8");

  const response = await client.chat.completions.create({
    model: "gpt-5.4-mini",
    messages: [
      {
        role: "user",
        content: `请总结下面这个 Markdown 文件，并列出关键功能：\n\nMarkdown file: ${MARKDOWN_PATH}\n\n${markdown}`,
      },
    ],
  });

  console.log(response.choices[0].message.content);
  ```
</CodeGroup>

## 使用建议

* 文件很长时，先删除无关日志、重复目录和生成内容。
* 需要模型引用来源时，保留标题层级、章节名和列表编号。
* 让模型输出结构化结果时，结合 [结构化输出](/zh/guide/structured-output)。
* 如果同时上传图片、PDF 与 Markdown，请在提示词中说明每个附件的用途。

<Warning>
  Markdown 文件可能包含内部链接、密钥示例、配置片段或私有代码。上传或通过 API 发送前，请先删除敏感内容。
</Warning>

## 后续阅读

* [对话](/zh/platform/playground)
* [快速入门](/zh/overview/quickstart)
* [结构化输出](/zh/guide/structured-output)