> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moxus.ai/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`。下面示例展示最直接的请求结构：

<CodeGroup>
  ```bash cURL theme={null}
  MARKDOWN_CONTENT="$(cat README.md)"

  curl https://moxus.ai/v1/chat/completions \
    -H "Authorization: Bearer sk-你的密钥" \
    -H "Content-Type: application/json" \
    -d "$(jq -n --arg content "$MARKDOWN_CONTENT" '{
      model: "gpt-4o",
      messages: [
        {
          role: "user",
          content: "请总结下面这个 Markdown 文件，并列出关键功能：\n\nMarkdown file: README.md\n\n\($content)"
        }
      ]
    }')"
  ```

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

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

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

  response = client.chat.completions.create(
      model="gpt-4o",
      messages=[
          {
              "role": "user",
              "content": f"请总结下面这个 Markdown 文件，并列出关键功能：\n\nMarkdown file: README.md\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: "sk-你的密钥",
    baseURL: "https://moxus.ai/v1",
  });

  const markdown = readFileSync("README.md", "utf8");

  const response = await client.chat.completions.create({
    model: "gpt-4o",
    messages: [
      {
        role: "user",
        content: `请总结下面这个 Markdown 文件，并列出关键功能：\n\nMarkdown file: README.md\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)