很多人第一次碰 ollama-main，卡在两个地方：一是克隆下来一堆目录不知道哪个是入口，二是装完照着 README 敲命令，服务起不来又不报明显错误。这篇按「目录看什么、启动走哪几步、报错往哪查」的顺序捋一遍，帮你把本地跑通这件事拆成可核对的动作，而不是背命令。
很多人第一次碰 ollama-main，卡的地方其实很朴素：克隆下来一屏目录，不知道哪个是入口；装完照着 README 敲命令，服务没起来，终端也不给你一句像样的报错。这篇不背命令，按「目录看什么、启动走哪几步、报错往哪查」拆成能核对的动作，让你知道每一步做完该看到什么现象。
有个前提先说清楚：下面讲的顺序是给本地部署新手用的通用路径。如果你是在容器里跑、或者团队已经封装好了启动脚本，那目录结构和启动方式都可能不一样，这时候优先看当前版本的说明文档，别硬套。下面所有涉及具体版本、具体资源占用的数字，一律到站内对应页面核对当时的数值。
先认清 ollama-main 里每个目录的职责
看目录别从子目录开始翻，先站根目录。根目录那几类文件决定你用什么方式把它拉起来：说明文档告诉你官方推荐的启动姿势，构建脚本和依赖清单告诉你要准备什么环境。这些没看明白就去翻内部实现，等于还没找到门就研究门锁结构。
| 目录类别 | 大致放什么 | 你要改东西时去哪找 |
|---|---|---|
| 命令层 / 入口 | 启动、拉取、管理等对外命令的入口逻辑 | 想改命令行为、加自定义子命令时看这里 |
| 服务层 | 后台服务的启动、监听、生命周期管理 | 服务起不来、端口不对、无法常驻时优先看 |
| 模型与运行时 | 模型加载、推理调度、资源分配相关 | 换模型、调显存占用、看加载失败原因时看 |
| 接口层 | 对外暴露的 HTTP 接口与请求处理 | 别的程序连不上、返回格式不对时看 |
- 根目录先看入口与配置：说明文档、构建脚本、依赖清单这类文件决定你用什么方式拉起它
- 按「命令层 / 服务层 / 模型与运行时 / 接口层」四块给目录归类，改配置、看日志、找模型逻辑各有各的位置
- 分清「编译产物」和「源码目录」：在源码目录里找可执行文件是最常见的白费功夫
- 拿不准某个目录名对应的概念，到 /ai-dict/category/tech 对照底层术语，再决定要不要往下钻
启动流程：从拿到代码到本地能对话
整条链路按五步走：装依赖、编译或构建、起后台服务、拉模型、发一次请求验证。关键在于每一步都要有能看到的成功标志，别一路敲到底再回头找问题。哪一步没有可见反馈，就停在那一步查，而不是继续往下。
- 装依赖按依赖清单准备环境。验证方式：依赖检查命令能跑通、不报缺失，而不是「我装过了」。缺依赖时的报错往往出现在后面的构建阶段，回头再补更费时间。
- 编译或构建按文档走构建流程，产物会出现在指定的输出位置。验证方式：能在输出目录找到可执行文件，而不是在源码目录里反复找。
- 起后台服务把服务拉起来，注意它监听的是本地哪个端口。验证方式：进程在、端口在被监听，两个都要确认，只看其中一个容易误判。
- 拉一个模型先用体积小的模型做链路验证。验证方式：模型出现在本地模型列表里，不是「命令没报错」就算完。
- 发一次请求验证向本地接口发一次最简单的请求，看是否拿到正常返回。验证方式：有正常响应内容，而不是连接超时或空响应。
端口这块要单独想一下：服务默认监听本地地址，能不能被局域网其他机器访问、要不要改绑定地址，取决于你是本机自用还是给别人当后端。前者不必动，后者才需要改，改完记得确认防火墙那一层也放行。具体的默认端口和参数写法，以当前版本说明和 /ai-dict/category/infra 里的术语为准。
起不来时的排查顺序
第一步先分类：是「安装层」还是「运行层」。命令都找不到，属于安装或环境变量没配好；命令能跑但服务不通，属于运行层，两条路的排查方向完全不同，混着查只会越查越乱。
| 现象 | 大概率在哪一层 | 先查什么 |
|---|---|---|
| 敲命令提示找不到 | 安装层 | 命令是否在 PATH 里、构建产物路径对不对 |
| 命令能跑但连不上服务 | 运行层 | 服务进程在不在、端口有没有被监听 |
| 服务在、客户端报错 | 链路层 | 客户端填的地址和端口跟服务实际监听的是否一致 |
| 卡住不动、没有明显报错 | 资源层 | 内存、显存、磁盘空间是否够 |
- 按「服务是否在跑 → 端口是否被占 → 模型是否真的拉下来了 → 客户端地址填对没有」的顺序查，不要跳步
- 资源类是高频原因：内存、显存、磁盘不够时，表现常常是卡住或静默失败，而不是清楚报错
- 接口连不上时先量基线，到 /tools/speed-test 看当下的连通与响应情况，再判断是服务问题还是网络问题
- 确认接口地址和端点怎么写，用 /ai-dict/category/infra 里的术语对照，避免地址拼错却一直查服务
跑通之后往哪走
本地能对话只是起点。接下来大致两个方向：一是换模型、比不同参数量和量化档位的差异，二是把它接进别的应用或知识库当后端。这两个方向的准备工作不一样，别在启动环节反复折腾。
换模型之前建议先算一遍资源：不同参数量、不同量化档位对显存和内存的要求差别很大，先到 /models/deploy 做一遍显存与配置测算，再决定拉哪个，能少走不少回头路。要对比不同方案的实际开销，到 /price-watch 看当时追踪到的数字，别凭印象拍脑袋。
集成层面的事，判断标准是「启动环节是否已经稳定」。启动都不稳就先别接应用，否则报错来源会混在一起，排查成本翻倍。另外版本更新后启动方式可能变，遇到行为和旧笔记不一致时，优先对照当前版本说明和实际目录结构，而不是沿用半年前的记录。
下一步把本地链路跑通后，去站内模型部署测算页核对资源和配置方案，再决定下一个要加载的模型；顺便看看价格追踪页当前记录的方案开销，心里有个数。→常见问题
ollama-main 是不是必须自己编译才能用？
不一定。看你要什么：只想在本地跑模型，用现成的安装包更省事；要改源码、追新特性或做二次开发，才需要从 main 分支自己构建。先用现成方式把模型跑起来，再决定要不要进源码这条路，顺序反了会很挫败。
服务能启动，但客户端连不上，先查哪里？
按这个顺序：服务进程是否真的在后台活着；监听端口有没有被别的程序占；客户端填的地址和端口跟服务实际监听的是否一致。如果服务是绑在本机回环地址上的，局域网其他机器连不上是正常的，需要改绑定配置。
拉模型很慢或者卡住不动，是配置问题吗？
多数时候是网络和磁盘的问题，不是配置写错了。先确认磁盘剩余空间够不够放下模型文件，再看下载链路是否被限速或中断。反复卡在同一个进度就中断重试，比一直干等更有效。模型文件多大、本地该怎么估，可以到 /models/deploy 按参数量和量化档位算一遍。
